Back to Details

deployment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ContextVM Deployment

ContextVM 部署

Deploy ContextVM servers and clients in production environments.
在生产环境中部署ContextVM服务器与客户端。

Environment Variables

环境变量

Required

必填项

VariableDescriptionExample
SERVER_PRIVATE_KEY
Server's Nostr private key (hex)
32-byte-hex-string
CLIENT_PRIVATE_KEY
Client's Nostr private key (hex)
32-byte-hex-string
变量名称描述示例
SERVER_PRIVATE_KEY
服务器的Nostr私钥（十六进制）
32-byte-hex-string
CLIENT_PRIVATE_KEY
客户端的Nostr私钥（十六进制）
32-byte-hex-string

Optional

可选项

VariableDescriptionDefault
RELAYS
Comma-separated relay URLs
wss://relay.contextvm.org
LOG_LEVEL
Logging verbosity
info
LOG_DESTINATION
Where to write logs
stderr
LOG_FILE
Log file path (if destination=file)-
ENCRYPTION_MODE
optional
, 
required
, 
disabled
optional
变量名称描述默认值
RELAYS
逗号分隔的中继URL列表
wss://relay.contextvm.org
LOG_LEVEL
日志详细程度
info
LOG_DESTINATION
日志输出位置
stderr
LOG_FILE
日志文件路径（当输出位置为file时）-
ENCRYPTION_MODE
optional
, 
required
, 
disabled
optional

Docker Deployment

Docker 部署

Basic Server Container

基础服务器容器

dockerfile
FROM oven/bun:alpine

WORKDIR /app

COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .

ENV SERVER_PRIVATE_KEY=""
ENV RELAYS="wss://relay.contextvm.org,wss://cvm.otherstuff.ai"
ENV LOG_LEVEL="info"

EXPOSE 3000

CMD ["bun", "run", "server.ts"]
dockerfile
FROM oven/bun:alpine

WORKDIR /app

COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

COPY . .

ENV SERVER_PRIVATE_KEY=""
ENV RELAYS="wss://relay.contextvm.org,wss://cvm.otherstuff.ai"
ENV LOG_LEVEL="info"

EXPOSE 3000

CMD ["bun", "run", "server.ts"]

Docker Compose

Docker Compose

yaml
version: "3.8"
services:
  cvm-server:
    build: .
    environment:
      - SERVER_PRIVATE_KEY=${SERVER_PRIVATE_KEY}
      - RELAYS=wss://relay.contextvm.org,wss://cvm.otherstuff.ai
      - LOG_LEVEL=info
      - ENCRYPTION_MODE=optional
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
See 
assets/docker-compose.yml
 for complete example.
yaml
version: "3.8"
services:
  cvm-server:
    build: .
    environment:
      - SERVER_PRIVATE_KEY=${SERVER_PRIVATE_KEY}
      - RELAYS=wss://relay.contextvm.org,wss://cvm.otherstuff.ai
      - LOG_LEVEL=info
      - ENCRYPTION_MODE=optional
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
完整示例请查看
assets/docker-compose.yml
。

Relay Configuration

中继配置

Recommended Public Relays

推荐的公共中继

wss://relay.contextvm.org
wss://cvm.otherstuff.ai
wss://nos.lol
wss://relay.contextvm.org
wss://cvm.otherstuff.ai
wss://nos.lol

Production Considerations

生产环境注意事项

  • Use 3-5 relays for redundancy
  • Include at least 2 geographically distributed
  • Monitor relay uptime
  • Have backup relay list ready
  • 使用3-5个中继以实现冗余
  • 至少包含2个地理分布分散的中继
  • 监控中继的在线状态
  • 准备好备用中继列表

Private Relay Setup

私有中继搭建

For sensitive deployments:
typescript
const relayPool = new ApplesauceRelayPool([
  "wss://private-relay.your-domain.com",
]);
对于敏感部署场景：
typescript
const relayPool = new ApplesauceRelayPool([
  "wss://private-relay.your-domain.com",
]);

Security Best Practices

安全最佳实践

Key Management

密钥管理

✓ DO:
  • Store keys in environment variables
  • Use secret management, if the security of the server requires it (AWS Secrets Manager, HashiCorp Vault)
✗ DON'T:
  • Hardcode keys in source
  • Commit keys to version control
  • Log private keys
  • Share keys between services
✓ 建议：
  • 将密钥存储在环境变量中
  • 若服务器安全性要求较高，使用密钥管理服务（AWS Secrets Manager、HashiCorp Vault）
✗ 禁止：
  • 在源代码中硬编码密钥
  • 将密钥提交到版本控制系统
  • 记录私钥
  • 在多个服务之间共享密钥

Access Control

访问控制

typescript
// Whitelist specific clients
const transport = new NostrServerTransport({
  signer,
  relayHandler: relayPool,
  allowedPublicKeys: [
    process.env.CLIENT_1_PUBKEY!,
    process.env.CLIENT_2_PUBKEY!,
  ],
});
typescript
// 白名单指定客户端
const transport = new NostrServerTransport({
  signer,
  relayHandler: relayPool,
  allowedPublicKeys: [
    process.env.CLIENT_1_PUBKEY!,
    process.env.CLIENT_2_PUBKEY!,
  ],
});

Health Checks

健康检查

Server Health Check

服务器健康检查

typescript
async function healthCheck(server: McpServer): Promise<boolean> {
  try {
    // Check if server responds to ping
    await server.ping();
    return true;
  } catch {
    return false;
  }
}
typescript
async function healthCheck(server: McpServer): Promise<boolean> {
  try {
    // 检查服务器是否响应ping请求
    await server.ping();
    return true;
  } catch {
    return false;
  }
}

Docker Health Check

Docker健康检查

dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD bun run healthcheck.ts || exit 1
dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD bun run healthcheck.ts || exit 1

Monitoring

监控

Structured Logging

结构化日志

typescript
import { createLogger } from "@contextvm/sdk/core";

const logger = createLogger("server");

// Production log format
logger.info("request.completed", {
  module: "server",
  method: "tools/call",
  tool: "echo",
  clientPubkey: pubkey.slice(0, 8) + "...",
  durationMs: 45,
});
typescript
import { createLogger } from "@contextvm/sdk/core";

const logger = createLogger("server");

// 生产环境日志格式
logger.info("request.completed", {
  module: "server",
  method: "tools/call",
  tool: "echo",
  clientPubkey: pubkey.slice(0, 8) + "...",
  durationMs: 45,
});

Metrics to Track

需跟踪的指标

  • Request rate and latency
  • Error rate by type
  • Active connections
  • Relay connection status
  • Event publish/subscribe rates
See 
references/monitoring.md
 for detailed monitoring setup.
  • 请求速率与延迟
  • 按类型统计的错误率
  • 活跃连接数
  • 中继连接状态
  • 事件发布/订阅速率
详细的监控搭建步骤请查看
references/monitoring.md
。

Production Checklist

生产环境检查清单

  • Keys in environment/secrets manager
  • Logging configured appropriately
  • Health checks implemented
  • Error handling in place
  • Graceful shutdown handling
  • Resource limits set (Docker)
  • Monitoring/alerting configured
  • 密钥已存储在环境变量/密钥管理器中
  • 日志已正确配置
  • 已实现健康检查
  • 已部署错误处理机制
  • 已配置优雅关机处理
  • 已设置资源限制（Docker）
  • 已配置监控/告警