> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose 部署与蓝绿发布

> 使用 Docker Compose 与 Nginx 反向代理部署 Profy 的完整指南，涵盖蓝绿发布零停机流程，以及 Core、Web 与 Agent Runtime 的编排。

# 部署指南

Profy 使用 Docker Compose 进行容器化部署，支持蓝绿发布策略实现零停机更新。生产环境通过 Nginx 反向代理统一入口，提供 SSL 终止和静态资源缓存。

## 部署架构

```mermaid theme={null}
graph TB
    Internet[公网] --> Nginx["Nginx<br/>SSL 终止 · 反向代理"]

    subgraph Docker["Docker Compose"]
        Web["profy-web<br/>Next.js :3000"]
        Core["profy-core<br/>Hono :8080"]
        Redis["Redis 7<br/>:6379"]
    end

    Nginx -->|"/*"| Web
    Nginx -->|"/api/*"| Core

    Core --> PostgreSQL[(PostgreSQL)]
    Core --> Redis
    Core --> S3[(S3)]

    Web --> Core

    style Nginx fill:#f0f4ff,stroke:#4a6cf7
    style Docker fill:#e8faf0,stroke:#10b981
```

## Docker Compose

### 服务组成

| 服务      | 镜像               | 端口   | 说明                 |
| ------- | ---------------- | ---- | ------------------ |
| `core`  | `profy-core`     | 8080 | Hono API，依赖 Redis  |
| `web`   | `profy-web`      | 3000 | Next.js 前端，依赖 Core |
| `redis` | `redis:7-alpine` | 6379 | 会话存储 / 缓存 / 限流     |

### 快速启动

```bash theme={null}
cd deploy/docker
docker compose up -d
```

### 多阶段构建

Dockerfile 采用多阶段构建，分离构建和运行环境：

```mermaid theme={null}
graph LR
    PB["packages-builder<br/>构建共享包"] --> CB["core-builder<br/>构建 Core API"]
    PB --> WB["web-builder<br/>构建 Next.js"]
    CB --> CoreImg["core<br/>运行镜像"]
    WB --> WebImg["web<br/>运行镜像"]

    style PB fill:#dbeafe,stroke:#3b82f6
    style CoreImg fill:#fff3e8,stroke:#f59e0b
    style WebImg fill:#e8faf0,stroke:#10b981
```

| 阶段                 | 作用                                         |
| ------------------ | ------------------------------------------ |
| `packages-builder` | 构建 `@profy/types`、`db`、`auth`、`ui`、`fetch` |
| `core-builder`     | 构建 Core API                                |
| `web-builder`      | 构建 Next.js 应用                              |
| `core`             | Core 运行镜像 + `start-core.sh`                |
| `web`              | Web 运行镜像 + `start-web.sh`                  |
| `production`       | 合并镜像（向后兼容）                                 |

### 启动脚本

**`start-core.sh`：**

1. 等待 PostgreSQL 就绪
2. 执行 `drizzle-kit push`（数据库迁移）
3. 启动 Core API

**`start-web.sh`：**

1. 等待 Core API 健康检查通过
2. 启动 Next.js 服务

## 蓝绿部署

蓝绿部署实现零停机发布，部署脚本位于 `deploy/scripts/`。

### 发布流程

```mermaid theme={null}
sequenceDiagram
    participant CI as 部署脚本
    participant Blue as 蓝色环境 (:3000)
    participant Green as 绿色环境 (:3001)
    participant Nginx as Nginx

    Note over Blue: 当前生产环境

    CI->>Green: 1. 构建 & 启动新版本
    CI->>Green: 2. 执行健康检查
    Green-->>CI: 健康检查通过

    CI->>Nginx: 3. 切换上游到 :3001
    Nginx->>Green: 流量切换
    Note over Green: 新版本服务流量

    CI->>Blue: 4. 停止旧版本
    Note over Blue: 资源释放
```

### 部署脚本

| 脚本                     | 用途     | 目标              |
| ---------------------- | ------ | --------------- |
| `deploy-production.sh` | 生产环境部署 | `app.profy.cn`  |
| `deploy-test.sh`       | 测试环境部署 | `test.profy.cn` |

关键步骤：

1. 本地构建 Docker 镜像
2. 推送到目标服务器
3. 启动新版本容器（使用备用端口）
4. 健康检查通过后切换 Nginx 上游
5. 停止旧版本容器

## Nginx 配置

### 路由规则

```nginx theme={null}
server {
    listen 443 ssl;
    server_name app.profy.cn;

    # SSL 配置
    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Next.js 前端
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # SSE 支持
    location /api/claw/chat {
        proxy_pass http://127.0.0.1:3000;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}
```

### SSE 与 WebSocket

Nginx 需要为 SSE 和 WebSocket 连接做特殊配置：

| 配置项                        | 说明                 |
| -------------------------- | ------------------ |
| `proxy_buffering off`      | 禁用缓冲，确保 SSE 事件实时推送 |
| `proxy_cache off`          | 禁用缓存               |
| `proxy_read_timeout 300s`  | 延长读取超时，支持长连接       |
| `proxy_set_header Upgrade` | WebSocket 升级支持     |

### 配置同步

`deploy/nginx/nginx.sh` 将本地 Nginx 配置同步到服务器：

```bash theme={null}
./deploy/nginx/nginx.sh
```

## 环境变量

### Core API

| 变量               | 说明               | 示例                                       |
| ---------------- | ---------------- | ---------------------------------------- |
| `DATABASE_URL`   | PostgreSQL 连接字符串 | `postgresql://user:pass@host:5432/profy` |
| `REDIS_URL`      | Redis 连接地址       | `redis://localhost:6379`                 |
| `JWT_SECRET`     | JWT 签名密钥         | 随机字符串                                    |
| `S3_ENDPOINT`    | S3 端点            | `http://localhost:9000`                  |
| `S3_ACCESS_KEY`  | S3 访问密钥          | —                                        |
| `S3_SECRET_KEY`  | S3 密钥            | —                                        |
| `WECHAT_APP_ID`  | 微信支付应用 ID        | —                                        |
| `WECHAT_MCH_ID`  | 微信支付商户号          | —                                        |
| `WECHAT_API_KEY` | 微信支付 API 密钥      | —                                        |
| `SMS_API_KEY`    | 短信服务密钥           | —                                        |

### Web 前端

| 变量                    | 说明            | 示例                     |
| --------------------- | ------------- | ---------------------- |
| `NEXT_PUBLIC_API_URL` | 公开 API 地址     | `https://app.profy.cn` |
| `CORE_API_BASE`       | Core API 内部地址 | `http://core:8080`     |

## 健康检查

| 端点                | 服务   | 用途        |
| ----------------- | ---- | --------- |
| `GET /health`     | Core | 基础存活检查    |
| `GET /api/health` | Core | API 层健康检查 |

部署脚本在切换流量前会轮询健康检查端点，确保新版本完全就绪后再接入流量。

## 声明式 Sandbox（E2B / Docker）

生产默认以 **单机 Docker Compose** 交付 Core、Web、Redis 等控制面服务。Expert 对话运行在 **声明式 Sandbox**：本地与自建环境通常对应 **Docker** 沙箱模板；云上可对接 **E2B** 等提供商，由 Core 完成创建、健康检查、暂停与销毁。Agent 进程与 SSE 端点位于 Sandbox 内的 **Agent Runtime**（`services/agent-runtime`），不再依赖 Kubernetes Pod 或集群内 Ingress。

对接云沙箱时需配置 Core / Agent Runtime 侧的环境变量与密钥（详见各环境 `.env.example` 与运维 Runbook）。

## Make 命令

| 命令                   | 说明                                            |
| -------------------- | --------------------------------------------- |
| `make deploy-p`      | 部署生产环境（Core + Web）                            |
| `make deploy-p-core` | 仅部署 Core                                      |
| `make deploy-p-web`  | 仅部署 Web                                       |
| `make deploy-t`      | 部署测试环境                                        |
| `make deploy-n`      | 同步 Nginx 配置                                   |
| `make dev`           | 本地编排（含 Core、Web、Agent Runtime 等，见 `Makefile`） |

## 相关链接

<CardGroup cols={2}>
  <Card title="系统架构" icon="sitemap" href="/zh/documentation/architecture/overview">
    Nginx 路由和双层架构设计
  </Card>

  <Card title="Agent 平台" icon="robot" href="/zh/documentation/agent">
    Expert、Agent Runtime 与 Sandbox 交互
  </Card>
</CardGroup>