From e082cda8b7526b85e46108692731fa840c335987 Mon Sep 17 00:00:00 2001 From: Developer Date: Mon, 1 Dec 2025 20:47:34 -0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=8CMPC-System=20=E9=83=A8=E7=BD=B2?= =?UTF-8?q?=E5=9C=A8=20Nginx=20=E6=9C=8D=E5=8A=A1=E5=99=A8=20192.168.1.100?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 架构更新: - Nginx + MPC-System 服务器 (192.168.1.100) - Nginx 反向代理 (80/443) - MPC-System Go 服务 (4000) - 后端微服务服务器 (192.168.1.111) - 所有 NestJS 微服务 - mpc-service 调用 192.168.1.100:4000 新增内容: - MPC-System 部署指南 (systemd/Docker 两种方式) - MPC-System API 端点说明 - 防火墙配置 (只允许后端服务器访问) - MPC 相关故障排查 - 健康检查命令更新 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../identity-service/DEPLOYMENT_GUIDE.md | 322 ++++++++++++++++-- 1 file changed, 286 insertions(+), 36 deletions(-) diff --git a/backend/services/identity-service/DEPLOYMENT_GUIDE.md b/backend/services/identity-service/DEPLOYMENT_GUIDE.md index 9ed88b61..0f85c984 100644 --- a/backend/services/identity-service/DEPLOYMENT_GUIDE.md +++ b/backend/services/identity-service/DEPLOYMENT_GUIDE.md @@ -12,22 +12,31 @@ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ -│ Nginx 服务器 (公网) │ +│ Nginx + MPC-System 服务器 192.168.1.100 (公网) │ │ https://rwaapi.szaiai.com │ │ │ -│ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ /etc/nginx/conf.d/rwaapi.conf │ │ -│ │ │ │ -│ │ /api/v1/user/* → 192.168.1.111:3000 (Identity) │ │ -│ │ /api/v1/auth/* → 192.168.1.111:3000 (Identity) │ │ -│ │ /api/v1/wallet/* → 192.168.1.111:3002 (Wallet) │ │ -│ │ /api/v1/trading/* → 192.168.1.111:3002 (Wallet) │ │ -│ │ /api/v1/planting/* → 192.168.1.111:3003 (Planting) │ │ -│ │ /api/v1/referral/* → 192.168.1.111:3004 (Referral) │ │ -│ │ /api/v1/mining/* → 192.168.1.111:3005 (Reward) │ │ -│ │ /api/v1/ranking/* → 192.168.1.111:3007 (Leaderboard) │ │ -│ │ /api/v1/telemetry/*→ 192.168.1.111:3008 (Reporting) │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ +│ ┌────────────────────────────────────────────────────────────────────────┐ │ +│ │ Nginx 反向代理 │ │ +│ │ /etc/nginx/conf.d/rwaapi.conf │ │ +│ │ │ │ +│ │ /api/v1/user/* → 192.168.1.111:3000 (Identity) │ │ +│ │ /api/v1/auth/* → 192.168.1.111:3000 (Identity) │ │ +│ │ /api/v1/wallet/* → 192.168.1.111:3002 (Wallet) │ │ +│ │ /api/v1/trading/* → 192.168.1.111:3002 (Wallet) │ │ +│ │ /api/v1/planting/* → 192.168.1.111:3003 (Planting) │ │ +│ │ /api/v1/referral/* → 192.168.1.111:3004 (Referral) │ │ +│ │ /api/v1/mining/* → 192.168.1.111:3005 (Reward) │ │ +│ │ /api/v1/ranking/* → 192.168.1.111:3007 (Leaderboard) │ │ +│ │ /api/v1/telemetry/*→ 192.168.1.111:3008 (Reporting) │ │ +│ └────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────────────────┐ │ +│ │ MPC-System (Go 服务) │ │ +│ │ localhost:4000 │ │ +│ │ • TSS 密钥生成 (Keygen) │ │ +│ │ • TSS 签名 (Sign) │ │ +│ │ • 密钥分片管理 │ │ +│ └───────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────┬───────────────────────────────────────────┘ │ 内网 ▼ @@ -35,10 +44,13 @@ │ 后端服务器 192.168.1.111 │ │ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ -│ │ Identity │ │ MPC │ │ Wallet │ │ Planting │ │ +│ │ Identity │ │ MPC-Service │ │ Wallet │ │ Planting │ │ │ │ :3000 │ │ :3001 │ │ :3002 │ │ :3003 │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ └───────────────┘ │ -│ │ +│ │ │ │ +│ │ │ 调用 MPC-System │ +│ │ └──────────────────────► 192.168.1.100:4000 │ +│ │ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ Referral │ │ Reward │ │ Authorization │ │ Leaderboard │ │ │ │ :3004 │ │ :3005 │ │ :3006 │ │ :3007 │ │ @@ -56,14 +68,35 @@ └─────────────────────────────────────────────────────────────────────────────┘ ``` -## 2. 后端服务端口规划 +### 服务器角色说明 -所有后端服务部署在 **192.168.1.111** 服务器上： +| 服务器 | IP 地址 | 角色 | 部署服务 | +|-------|---------|------|---------| +| Nginx + MPC 服务器 | 192.168.1.100 (公网) | API 网关 + MPC 核心 | Nginx, MPC-System (Go) | +| 后端服务器 | 192.168.1.111 (内网) | 业务微服务 | 所有 NestJS 微服务 + 基础设施 | + +### 为什么 MPC-System 部署在 Nginx 服务器上？ + +**安全隔离原则**: MPC-System 是处理密钥分片的核心安全组件，与业务数据库隔离部署可以： +1. 减少攻击面 - 即使业务服务器被入侵，MPC 密钥分片仍然安全 +2. 物理隔离 - 密钥分片和业务数据在不同机器上 +3. 独立运维 - MPC 系统可以独立升级和维护 + +## 2. 服务端口规划 + +### 2.1 Nginx + MPC 服务器 (192.168.1.100) + +| 服务名称 | 端口 | 说明 | +|---------|------|------| +| Nginx | 80, 443 | HTTP/HTTPS 反向代理 | +| MPC-System (Go) | 4000 | TSS 密钥生成、签名服务 | + +### 2.2 后端服务器 (192.168.1.111) | 服务名称 | 端口 | API 前缀 | 说明 | |---------|------|----------|------| | Identity Service | 3000 | `/api/v1` | 用户身份、认证、钱包创建 | -| MPC Service | 3001 | `/api/v1` | MPC 密钥分片管理 (内部) | +| MPC Service (NestJS) | 3001 | `/api/v1` | MPC 中间层，调用 MPC-System | | Wallet Service | 3002 | `/api/v1` | 钱包余额、交易、充值 | | Planting Service | 3003 | `/api/v1` | 认种业务 | | Referral Service | 3004 | `/api/v1` | 推荐关系、分享链接 | @@ -73,6 +106,14 @@ | Reporting Service | 3008 | `/api/v1` | 遥测统计、报表 | | Backup Service | 3009 | - | MPC 备份 (内部服务) | +### 2.3 MPC 调用链路 + +``` +用户请求 → Identity Service (3000) → MPC Service (3001) → MPC-System (192.168.1.100:4000) + ↓ + TSS 密钥生成/签名 +``` + ## 3. Nginx 配置文件 ### 3.1 目录结构 @@ -386,9 +427,185 @@ server { } ``` -## 4. 后端服务器配置 (192.168.1.111) +## 4. MPC-System 部署 (192.168.1.100) -### 4.1 Docker Compose 部署文件 +MPC-System 是一个独立的 Go 服务，负责 TSS (Threshold Signature Scheme) 密钥生成和签名操作。 + +### 4.1 系统要求 + +- Go 1.21+ +- 最小 2GB RAM +- 10GB 磁盘空间 + +### 4.2 部署方式 + +#### 方式一: 直接运行 (推荐生产环境) + +```bash +# 1. 创建部署目录 +mkdir -p /opt/mpc-system +cd /opt/mpc-system + +# 2. 下载或复制编译好的二进制文件 +# 从构建服务器复制 mpc-system 可执行文件 +scp build-server:/path/to/mpc-system . + +# 3. 创建配置文件 +cat > config.yaml << 'EOF' +server: + host: 0.0.0.0 + port: 4000 + +# TSS 配置 +tss: + threshold: 2 # 签名阈值 (t of n) + parties: 3 # 总参与方数量 + +# 日志配置 +log: + level: info + format: json + output: /var/log/mpc-system/mpc.log + +# 安全配置 +security: + # 只允许后端服务器访问 + allowed_ips: + - 192.168.1.111 + # API 认证密钥 + api_key: ${MPC_API_KEY} +EOF + +# 4. 创建日志目录 +mkdir -p /var/log/mpc-system + +# 5. 创建 systemd 服务 +cat > /etc/systemd/system/mpc-system.service << 'EOF' +[Unit] +Description=MPC System - TSS Key Generation and Signing Service +After=network.target + +[Service] +Type=simple +User=mpc +Group=mpc +WorkingDirectory=/opt/mpc-system +ExecStart=/opt/mpc-system/mpc-system -config /opt/mpc-system/config.yaml +Restart=always +RestartSec=5 +Environment=MPC_API_KEY=your_secure_api_key_here + +# 安全限制 +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +ReadWritePaths=/var/log/mpc-system /opt/mpc-system/data + +[Install] +WantedBy=multi-user.target +EOF + +# 6. 创建专用用户 +useradd -r -s /bin/false mpc +chown -R mpc:mpc /opt/mpc-system /var/log/mpc-system + +# 7. 启动服务 +systemctl daemon-reload +systemctl enable mpc-system +systemctl start mpc-system + +# 8. 检查状态 +systemctl status mpc-system +curl http://localhost:4000/health +``` + +#### 方式二: Docker 部署 + +```bash +# 1. 创建 Dockerfile (如果需要) +cat > /opt/mpc-system/Dockerfile << 'EOF' +FROM golang:1.21-alpine AS builder +WORKDIR /app +COPY . . +RUN go build -o mpc-system ./cmd/main.go + +FROM alpine:3.19 +RUN apk add --no-cache ca-certificates +COPY --from=builder /app/mpc-system /usr/local/bin/ +COPY --from=builder /app/config.yaml /etc/mpc-system/ +EXPOSE 4000 +CMD ["mpc-system", "-config", "/etc/mpc-system/config.yaml"] +EOF + +# 2. 使用 docker-compose +cat > /opt/mpc-system/docker-compose.yml << 'EOF' +services: + mpc-system: + build: . + ports: + - "4000:4000" + environment: + - MPC_API_KEY=${MPC_API_KEY} + volumes: + - ./config.yaml:/etc/mpc-system/config.yaml:ro + - mpc_data:/opt/mpc-system/data + - mpc_logs:/var/log/mpc-system + restart: unless-stopped + # 网络隔离 - 只允许内网访问 + networks: + - internal + +networks: + internal: + driver: bridge + internal: true + +volumes: + mpc_data: + mpc_logs: +EOF + +# 3. 启动 +cd /opt/mpc-system +docker compose up -d +``` + +### 4.3 MPC-System API 端点 + +| 端点 | 方法 | 说明 | +|------|------|------| +| `/health` | GET | 健康检查 | +| `/api/v1/keygen` | POST | TSS 密钥生成 | +| `/api/v1/sign` | POST | TSS 签名 | +| `/api/v1/reshare` | POST | 密钥重新分片 | + +### 4.4 防火墙配置 + +```bash +# 只允许后端服务器 (192.168.1.111) 访问 MPC-System +iptables -A INPUT -p tcp --dport 4000 -s 192.168.1.111 -j ACCEPT +iptables -A INPUT -p tcp --dport 4000 -j DROP + +# 保存规则 +iptables-save > /etc/iptables/rules.v4 +``` + +### 4.5 环境变量 + +在 192.168.1.100 服务器上创建 `/opt/mpc-system/.env`: + +```bash +# MPC API 认证密钥 (与 mpc-service 配置一致) +MPC_API_KEY=your_very_secure_api_key_at_least_32_characters + +# 日志级别 +LOG_LEVEL=info +``` + +## 5. 后端服务器配置 (192.168.1.111) + +### 5.1 Docker Compose 部署文件 在 192.168.1.111 服务器上创建 `/opt/rwadurian/docker-compose.yml`: @@ -426,6 +643,8 @@ services: - DATABASE_URL=postgresql://postgres:${DB_PASSWORD}@postgres:5432/rwa_mpc - REDIS_HOST=redis - APP_ENV=production + # MPC-System 部署在 192.168.1.100 (Nginx 服务器) + - MPC_SYSTEM_URL=http://192.168.1.100:4000 depends_on: postgres: condition: service_healthy @@ -644,7 +863,7 @@ volumes: redis_data: ``` -### 4.2 数据库初始化脚本 +### 5.2 数据库初始化脚本 在 192.168.1.111 服务器上创建 `/opt/rwadurian/scripts/init-databases.sql`: @@ -662,7 +881,7 @@ CREATE DATABASE rwa_reporting; CREATE DATABASE rwa_backup; ``` -### 4.3 环境变量文件 +### 5.3 环境变量文件 在 192.168.1.111 服务器上创建 `/opt/rwadurian/.env`: @@ -683,9 +902,9 @@ SERVICE_JWT_SECRET=your_service_jwt_secret_for_internal_calls WALLET_ENCRYPTION_SALT=your_wallet_encryption_salt ``` -## 5. 部署步骤 +## 6. 部署步骤 -### 5.1 Nginx 服务器配置 +### 6.1 Nginx + MPC 服务器 (192.168.1.100) 配置 ```bash # 1. 安装 Nginx @@ -709,7 +928,7 @@ systemctl restart nginx systemctl enable nginx ``` -### 5.2 后端服务器 (192.168.1.111) 配置 +### 6.2 后端服务器 (192.168.1.111) 配置 ```bash # 1. 安装 Docker @@ -750,7 +969,7 @@ docker compose exec leaderboard-service npx prisma migrate deploy docker compose exec reporting-service npx prisma migrate deploy ``` -### 5.3 验证部署 +### 6.3 验证部署 ```bash # 从 Nginx 服务器测试 @@ -767,7 +986,7 @@ curl http://localhost:3000/api/v1/user/auto-create \ -d '{"deviceId": "test-device-123"}' ``` -## 6. API 端点对照表 +## 7. API 端点对照表 | 前端调用路径 | Nginx 转发 | 后端服务 | 端口 | |-------------|-----------|---------|------| @@ -786,9 +1005,9 @@ curl http://localhost:3000/api/v1/user/auto-create \ | `/api/v1/telemetry/*` | → | Reporting Service | 3008 | | `/api/v1/report/*` | → | Reporting Service | 3008 | -## 7. 监控与运维 +## 8. 监控与运维 -### 7.1 查看 Nginx 日志 +### 8.1 查看 Nginx 日志 ```bash # 访问日志 @@ -801,30 +1020,49 @@ tail -f /var/log/nginx/error.log grep "/api/v1/user" /var/log/nginx/access.log | tail -100 ``` -### 7.2 查看服务日志 +### 8.2 查看服务日志 ```bash -# 在 192.168.1.111 上执行 +# ======================================== +# 192.168.1.100 (Nginx + MPC 服务器) 日志 +# ======================================== +# MPC-System 日志 +tail -f /var/log/mpc-system/mpc.log +journalctl -u mpc-system -f +# ======================================== +# 192.168.1.111 (后端服务器) 日志 +# ======================================== # 查看所有服务日志 docker compose logs -f # 查看特定服务日志 docker compose logs -f identity-service +docker compose logs -f mpc-service docker compose logs -f wallet-service # 查看最近 100 行 docker compose logs --tail=100 identity-service ``` -### 7.3 服务健康检查 +### 8.3 服务健康检查 ```bash +# ======================================== +# 192.168.1.100 (Nginx + MPC 服务器) 健康检查 +# ======================================== +curl http://192.168.1.100:4000/health # MPC-System +curl https://rwaapi.szaiai.com/health # Nginx 反向代理 + +# ======================================== +# 192.168.1.111 (后端服务器) 健康检查 +# ======================================== # 检查所有服务状态 docker compose ps -# 检查特定服务健康 +# 检查各微服务健康 curl http://192.168.1.111:3000/health # Identity +curl http://192.168.1.111:3001/health # MPC Service (NestJS) curl http://192.168.1.111:3002/health # Wallet curl http://192.168.1.111:3003/health # Planting curl http://192.168.1.111:3004/health # Referral @@ -833,7 +1071,7 @@ curl http://192.168.1.111:3007/health # Leaderboard curl http://192.168.1.111:3008/health # Reporting ``` -### 7.4 重启服务 +### 8.4 重启服务 ```bash # 重启单个服务 @@ -846,7 +1084,7 @@ docker compose restart docker compose up -d --build identity-service ``` -## 8. 常见问题 +## 9. 常见问题 ### Q1: 502 Bad Gateway - 检查后端服务是否运行: `docker compose ps` @@ -866,6 +1104,18 @@ docker compose up -d --build identity-service - 检查 Docker 网络: `docker network inspect rwa-network` - 检查服务名解析: `docker compose exec identity-service ping wallet-service` +### Q5: MPC-System 连接失败 +- 检查 MPC-System 服务状态: `systemctl status mpc-system` (在 192.168.1.100 上) +- 检查 MPC-System 健康: `curl http://192.168.1.100:4000/health` +- 检查防火墙规则是否允许 192.168.1.111 访问 4000 端口 +- 检查 mpc-service 环境变量 `MPC_SYSTEM_URL` 是否正确设置为 `http://192.168.1.100:4000` +- 查看 MPC-System 日志: `tail -f /var/log/mpc-system/mpc.log` + +### Q6: TSS 密钥生成/签名超时 +- MPC 操作可能需要较长时间，检查超时配置 +- 确保网络延迟在合理范围内: `ping 192.168.1.100` +- 检查 MPC-System 资源使用: `htop` 或 `top` + --- **最后更新**: 2025-12-01