agent-fox/docs/deployment-guide.md

AgentFox 生产环境部署指南

架构概览

                    ┌──────────────────────────────────┐
                    │           Docker Network          │
   用户请求         │                                    │
  ────────▶  ┌──────┴──────┐                             │
             │    Nginx    │    /api/*                   │
             │   (Web)     │──────────▶┌─────────┐      │
             │   :80       │           │ Server  │      │
             │             │    /mcp/* │ (API)   │──┐   │
             │  SPA 静态   │──────▶┌───┤ :3000   │  │   │
             │  资源服务    │      │   └─────────┘  │   │
             └─────────────┘      │                 │   │
                                  │   ┌─────────┐  │   │
                                  └──▶│   MCP   │  │   │
                                      │ :3001   │──┤   │
                                      └─────────┘  │   │
                                                   ▼   │
                              ┌────────────┐  ┌───────┐│
                              │ PostgreSQL │  │ Redis ││
                              │   :5432    │  │ :6379 ││
                              └────────────┘  └───────┘│
                    └──────────────────────────────────┘

服务	镜像	端口	用途
web	nginx:alpine	80	前端 SPA + 反向代理（/api/ → server，/mcp/ → mcp）
server	node:20-alpine	3000	Express API：认证、项目管理、OpenAPI 导入解析
mcp	node:20-alpine	3001	MCP 协议服务：为 LLM 提供 API 文档查询工具
postgres	postgres:16-alpine	5432	主数据库：用户、项目、模块、端点数据
redis	redis:7-alpine	6379	会话缓存、速率限制

请求流向：用户浏览器 → Nginx(:80) → 静态 SPA 或反代到 Server/MCP → PostgreSQL + Redis

---

前置要求

• Docker Engine 24+ 和 Docker Compose V2
• 至少 2GB 内存、10GB 磁盘空间
• 一个可访问的域名（用于 HTTPS 和 OAuth 回调）

---

第一步：获取代码

git clone <repo-url> agent-fox
cd agent-fox

---

第二步：配置环境变量

cp .env.example .env

编辑 .env 文件：

必填项

# 先生成 3 个随机密钥
openssl rand -hex 32   # → JWT_SECRET
openssl rand -hex 32   # → JWT_REFRESH_SECRET
openssl rand -hex 32   # → API_KEY_ENCRYPTION_SECRET

JWT_SECRET=<粘贴第1个值>
JWT_REFRESH_SECRET=<粘贴第2个值>
API_KEY_ENCRYPTION_SECRET=<粘贴第3个值>

警告：这三个密钥一旦投入使用，切勿更换。更换 JWT_SECRET 会使所有已登录用户失效，更换 API_KEY_ENCRYPTION_SECRET 会使所有 API Key 不可用。

数据库（可选修改）

如需自定义数据库密码，同时修改 docker-compose.yml 和 .env：

DATABASE_URL=postgresql://myuser:MyStr0ngP@ss@postgres:5432/agentfox

对应修改 docker-compose.yml 中的 POSTGRES_USER / POSTGRES_PASSWORD。

OAuth 第三方登录（可选）

不配置则仅支持邮箱密码注册登录。配置方法详见 OAuth 注册指南。

# Google
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPx-xxx

# GitHub
GITHUB_CLIENT_ID=Ov23li...
GITHUB_CLIENT_SECRET=xxx

# Apple
APPLE_CLIENT_ID=com.example.agentfox
APPLE_TEAM_ID=xxx
APPLE_KEY_ID=xxx
APPLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----

# 回调地址（必须与第三方平台注册的一致）
OAUTH_CALLBACK_BASE_URL=https://你的域名
FRONTEND_URL=https://你的域名

完整 .env 示例

DATABASE_URL=postgresql://agentfox:agentfox@postgres:5432/agentfox
REDIS_URL=redis://redis:6379
JWT_SECRET=e0c33a89e22b6ace23a1718d388e2b20f4735b5ab58c5cffe8d31c8fbedb6910
JWT_REFRESH_SECRET=28f886e7af5b704b4c45440bd9db41706bf996601f78dd05ca98c7dce358c833
API_KEY_ENCRYPTION_SECRET=5917b3fdc14565ede76b118d672dc98cdffb90f8ee16d88e5e6c61eb86e56eb8
SERVER_PORT=3000
MCP_PORT=3001
MCP_BASE_URL=http://mcp:3001
OAUTH_CALLBACK_BASE_URL=https://你的域名
FRONTEND_URL=https://你的域名

---

第三步：构建并启动

docker compose up --build -d

首次启动过程：

1. Docker 构建 4 个镜像（约 3-5 分钟）
2. PostgreSQL 和 Redis 率先启动并通过健康检查
3. Server 启动时自动执行 prisma migrate deploy 创建数据库表
4. MCP 和 Web 随后启动

验证

# 确认 5 个服务全部 running
docker compose ps

# 期望输出：
# NAME        STATUS
# postgres    Up (healthy)
# redis       Up (healthy)
# server      Up
# mcp         Up
# web         Up

# 验证 API 可达
curl http://localhost/api/health

# 验证前端可达
curl -s http://localhost | head -5

访问 http://服务器IP 即可使用。

---

第四步：配置 HTTPS（生产必须）

方案 A：Caddy（推荐，自动 HTTPS）

# 安装 Caddy
sudo apt install -y caddy   # Debian/Ubuntu
# 或 brew install caddy     # macOS

创建 /etc/caddy/Caddyfile：

你的域名 {
    reverse_proxy localhost:80
}

sudo systemctl restart caddy

Caddy 会自动申请和续期 Let's Encrypt 证书。

方案 B：修改 Nginx 配置

将 SSL 证书挂载进 web 容器，修改 packages/web/nginx.conf 添加 443 监听。

方案 C：云厂商负载均衡

将 HTTPS 终止放在云厂商 SLB/ALB 上，后端指向服务器的 80 端口。

---

生产加固清单

数据库安全

# docker-compose.yml
postgres:
  environment:
    POSTGRES_USER: agentfox_prod
    POSTGRES_PASSWORD: <使用 openssl rand -base64 24 生成>
  ports: []   # 生产环境移除端口映射，仅内部访问

Redis 安全

redis:
  command: redis-server --requirepass <密码>
  ports: []   # 生产环境移除端口映射

对应更新环境变量：

REDIS_URL=redis://:<密码>@redis:6379

资源限制

# docker-compose.yml 各服务添加
server:
  deploy:
    resources:
      limits:
        memory: 512M
        cpus: "1.0"

日志管理

# 防止日志文件无限增长
services:
  server:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

---

更新部署

# 拉取最新代码
git pull origin main

# 重新构建并重启（零停机：先构建再替换）
docker compose up --build -d

# 如果只更新了前端
docker compose build web && docker compose up -d web

# 如果只更新了后端
docker compose build server && docker compose up -d server

---

数据备份

PostgreSQL

# 备份
docker compose exec postgres pg_dump -U agentfox agentfox > backup_$(date +%Y%m%d).sql

# 恢复
cat backup_20260403.sql | docker compose exec -T postgres psql -U agentfox agentfox

定时备份（cron）

# 每天凌晨 3 点备份
0 3 * * * cd /path/to/agent-fox && docker compose exec -T postgres pg_dump -U agentfox agentfox | gzip > /backups/agentfox_$(date +\%Y\%m\%d).sql.gz

Redis

Redis 数据通过 redisdata volume 自动持久化（RDB 快照）。

---

常用运维命令

# === 服务管理 ===
docker compose up -d              # 启动
docker compose down                # 停止
docker compose restart server      # 重启单个服务
docker compose logs -f server      # 查看日志（实时）
docker compose logs --tail 100     # 最近 100 行

# === 调试 ===
docker compose exec server sh         # 进入 server 容器
docker compose exec postgres psql -U agentfox  # 进入数据库
docker compose exec redis redis-cli    # 进入 Redis

# === 数据库 ===
docker compose exec server npx prisma migrate deploy --schema=prisma/schema.prisma  # 手动迁移
docker compose exec postgres psql -U agentfox -c "\dt"     # 查看表
docker compose exec postgres psql -U agentfox -c "SELECT count(*) FROM \"User\""  # 查询用户数

# === 清理 ===
docker compose down -v             # ⚠️ 停止并删除所有数据
docker system prune -f             # 清理无用镜像/缓存

---

故障排查

现象	原因 & 解决
docker compose up 后 server 一直重启	查看 docker compose logs server，通常是数据库连接失败。确认 postgres 已 healthy
访问页面显示 502	server 或 mcp 未正常运行。docker compose ps 检查状态
登录报 500	检查 JWT_SECRET 是否已正确配置，docker compose logs server 查看详情
OAuth 回调报错	确认 .env 中 OAUTH_CALLBACK_BASE_URL 与第三方平台注册的回调地址完全一致（协议+域名）
MCP 工具连接失败	1) 确认 API Key 正确 2) docker compose logs mcp 查看错误 3) 确认 MCP URL 格式为 http(s)://域名/mcp/<projectId>
Redis 连接失败	docker compose exec redis redis-cli ping 应返回 PONG
数据库迁移失败	docker compose exec server npx prisma migrate deploy --schema=prisma/schema.prisma 手动执行并查看报错
磁盘空间不足	docker system prune -f 清理无用镜像，检查 pg 数据量