# 金山云内网 POC 部署手册

本文档记录 `2026-03-20` 的当前落地状态。当前环境已实现：

- 可访问
- 可注册登录
- 可创建 workspace
- 可连接 daemon 并跑 agent

---

## 1. 架构概览

### 1.1 拓扑与流量路径

- 业务机：`10.2.103.216`（Ubuntu 24.04）
- 外部入口：`agentteam.pingcap.com`
- 入口链路：公司内网 LB -> 网关 Nginx -> `10.2.103.216:3001`
- 业务机内部链路：本机 `nginx:3001` -> `agentteam-server:127.0.0.1:3002`

### 1.2 组件职责

- `agentteam-server`（systemd）
  - 监听：`127.0.0.1:3002`
  - 提供：`/api/*`、`/socket.io/*`、`/internal/*`
  - 不直接提供前端静态页面
- 本机 `nginx`（systemd）
  - 监听：`0.0.0.0:3001`
  - 提供前端静态页面（`/opt/agentteam/www`）
  - 反代 API / WebSocket 到 `127.0.0.1:3002`
- 外部 TiDB
  - 地址：`10.2.2.147:4000`
  - 用途：业务数据存储
- 归档存储
  - 当前驱动：`filesystem`
- 邮件通道
  - 当前驱动：`smtp`（公司飞书邮箱）

---

## 2. 安全组与网络要求

入站（Inbound）：

- `22/tcp`：仅运维来源 IP
- `3001/tcp`：仅公司网关 / LB 来源

出站（Outbound）：

- `4000/tcp` -> `10.2.2.147`（外部 TiDB）
- `443/tcp`（服务查询 npm latest daemon version）
- `587/tcp` -> `smtp.feishu.cn`（SMTP STARTTLS 发信）

---

## 3. 关键目录与服务文件

- 代码目录：`/opt/agentteam`
- 后端二进制：`/opt/agentteam/bin/agentteam-server`
- 迁移工具：`/opt/agentteam/bin/agentteam-schema`
- 前端静态资源：`/opt/agentteam/www`
- 服务环境变量：`/etc/agentteam/agentteam.env`
- systemd 服务：`/etc/systemd/system/agentteam-server.service`

---

## 4. 环境变量（统一说明）

编辑文件：`/etc/agentteam/agentteam.env`

```bash
# Runtime
AGENTTEAM_ENV=development
AGENTTEAM_PUBLIC_BASE_URL=https://agentteam.pingcap.com
AGENTTEAM_DAEMON_CONNECT_BASE_URL=https://agentteam.pingcap.com
AGENTTEAM_HTTP_ADDRESS=127.0.0.1:3002

# Daemon upgrade gate (optional; set during coordinated server/daemon cutover)
AGENTTEAM_DAEMON_MIN_VERSION=v1.0.2-rc.11

# Database
AGENTTEAM_DATABASE_DSN=admin:<URL_ENCODED_DB_PASSWORD>@tcp(10.2.2.147:4000)/agentteam?multiStatements=true&parseTime=true&loc=UTC

# Archive
AGENTTEAM_ARCHIVE_DRIVER=filesystem
AGENTTEAM_ARCHIVE_FILESYSTEM_ROOT=/var/lib/agentteam/archive

# Credential encryption (stable deployment state; files are generated if absent)
AGENTTEAM_APP_CREDENTIALS_KEY_FILE=/var/lib/agentteam/secrets/app_credentials_master_key
AGENTTEAM_ORG_CREDENTIALS_KEY_FILE=/var/lib/agentteam/secrets/org_credentials_master_key

# Mail (SMTP)
AGENTTEAM_MAIL_DRIVER=smtp
AGENTTEAM_MAIL_FROM_ADDRESS=agentteam@pingcap.com
AGENTTEAM_MAIL_SMTP_HOST=smtp.feishu.cn
AGENTTEAM_MAIL_SMTP_PORT=587
AGENTTEAM_MAIL_SMTP_USERNAME=agentteam@pingcap.com
AGENTTEAM_MAIL_SMTP_PASSWORD=<SMTP_PASSWORD>
AGENTTEAM_MAIL_SMTP_SECURITY=starttls
```

说明：

- 数据库密码若含 `#`，需 URL 编码为 `%23`
- 示例：`Pass#99` -> `Pass%2399`
- `AGENTTEAM_APP_CREDENTIALS_KEY_FILE` 用于 workspace 级 App / GitHub / Gitea / Agent LLM 凭据加密；`AGENTTEAM_ORG_CREDENTIALS_KEY_FILE` 只用于组织/飞书侧凭据，并作为历史 App/Agent 密文的读取 fallback。两个文件必须是部署级稳定状态，目录需由 `agentteam-server` 运行用户可写并纳入备份。部署脚本只读取 `/etc/agentteam/agentteam.env`，不会主动轮换这些 key。
- 如不用 key 文件，也可以设置对应的 `*_MASTER_KEY`；值必须是 base64 编码的 32 字节 key，且重启/发布间保持不变。
- 对外入口已经是 `https://agentteam.pingcap.com` 时，`AGENTTEAM_PUBLIC_BASE_URL` 和 `AGENTTEAM_DAEMON_CONNECT_BASE_URL` 都必须写成 `https://...`；不要写业务机内网 IP，也不要写 `http://...`
- `AGENTTEAM_DAEMON_MIN_VERSION` 是最低 daemon 版本硬门禁。留空或不设置时不启用；升级切换时设置为本次配套 daemon 的最低 release/tag（例如 `v1.0.2-rc.11`）。版本按 semver 比较，低版本、空版本或非法版本的 daemon 会收到 `upgrade_required`，需要先升级并重连。
- `AGENTTEAM_DAEMON_LATEST_VERSION_OVERRIDE` 只用于 latest/recommended 展示或提醒，不要用它代替 `AGENTTEAM_DAEMON_MIN_VERSION`。

---

## 5. 部署与更新（一键发布）

统一使用仓库脚本：`/opt/agentteam/scripts/deploy-main.sh`
脚本会自动执行：拉取 `origin/main` -> 构建前后端 -> 迁移 -> 重启服务 -> 健康检查。

### 5.1 前置条件

- 业务机已存在目录：`/opt/agentteam`
- 服务环境变量文件存在：`/etc/agentteam/agentteam.env`
- `agentteam` 用户具备 GitHub 仓库 `winkyao/agentteam` 读取权限（Deploy Key）
- 业务机已安装：`git`、`go`、`npm`、`rsync`、`curl`、`systemd`、`sudo`
- `/var/lib/agentteam/archive` 和 `/var/lib/agentteam/secrets` 已存在并归 `agentteam` 用户所有，用于持久化归档和凭据加密 key 文件

### 5.2 无中断预演（推荐先执行）

```bash
ssh root@10.2.103.216
cd /opt/agentteam
AGENTTEAM_SKIP_RESTART=1 bash scripts/deploy-main.sh
```

### 5.3 正式发布

```bash
ssh root@10.2.103.216
cd /opt/agentteam
bash scripts/deploy-main.sh
```

### 5.4 常用可覆盖参数（可选）

```bash
AGENTTEAM_APP_DIR=/opt/agentteam \
AGENTTEAM_BRANCH=main \
AGENTTEAM_SERVICE=agentteam-server \
AGENTTEAM_ENV_FILE=/etc/agentteam/agentteam.env \
AGENTTEAM_RUN_AS=agentteam \
AGENTTEAM_HEALTHCHECK_TIMEOUT_SEC=60 \
AGENTTEAM_HEALTHCHECK_INTERVAL_SEC=2 \
bash /opt/agentteam/scripts/deploy-main.sh
```

### 5.5 Release 脚本环境文件（如使用）

`scripts/release/deploy-release.sh` 使用本地 `AGENTTEAM_ENV_FILE_PATH` 作为源环境文件，默认是 `infra/aws-tokyo/agentteam.env.production`；部署时会先调用 `scripts/release/sync-env.sh`，把该文件同步到远端 `/etc/agentteam/agentteam.env`，再激活 release。

如果使用 release 脚本发布，也要把同一行写进本地 env 文件：

```env
AGENTTEAM_DAEMON_MIN_VERSION=v1.0.2-rc.11
```

然后运行：

```bash
AGENTTEAM_ENV_FILE_PATH=infra/aws-tokyo/agentteam.env.production \
bash scripts/release/deploy-release.sh
```

如只需要同步环境文件并重启服务，可运行：

```bash
AGENTTEAM_ENV_FILE_PATH=infra/aws-tokyo/agentteam.env.production \
bash scripts/release/sync-env.sh
```

### 5.6 从 standalone MeshX 升级到 unified release

`scripts/agentteam-prod-build-release.sh` 默认调用 `scripts/agentteam-prod-activate-release.sh`。
如果托管的 `/etc/agentteam/agentteam.env` 仍含已退役的 `AGENTTEAM_MESHX_BASE_URL`，activate 保留原文件
且继续执行；统一版本的 `central`、`workspace`、`all` profile 都不读取或校验该键，空值
和格式错误的值也会被静默忽略。回滚应恢复完整旧 release bundle，而不是依赖该键给
新版本重新接入 standalone MeshX。

不使用该 activate 脚本的手工部署也必须先停止并排空旧 standalone workers，再启动
unified workspace owners。无需在维护窗口前编辑 deployment-owned env；稳定后可把
`AGENTTEAM_MESHX_BASE_URL` 作为配置卫生清理，但它不是启动或回滚门禁。不要删除
MeshX 自有数据库、AGS 存储、automation 与 KB 配置；HTTP/public URL、AgentTeam core DSN
和 MaaS base URL 已统一由 `AGENTTEAM_*` 配置提供。

### 5.7 发布失败处理

- 若提示 `git working tree is dirty`：先清理工作区后再发布
- 若提示 `Permission denied (publickey)`：检查 `agentteam` 用户 Deploy Key
- 若迁移 preflight 失败：先按报错修复迁移状态，再重试发布

---

## 6. 启动状态与可用性检查

业务机本地：

```bash
systemctl is-active agentteam-server
systemctl is-active nginx

curl -fsS http://127.0.0.1:3002/healthz
curl -fsS http://127.0.0.1:3002/readyz
curl -I http://127.0.0.1:3001/
curl -fsS http://127.0.0.1:3001/api/public/config

ss -lntp | egrep ':22 |:3001 |:3002 '
```

外部入口（办公网）：

```bash
curl -I https://agentteam.pingcap.com/
curl https://agentteam.pingcap.com/api/public/config
```

---

## 7. daemon 接入验证

在 Web 创建 machine，拿到 `machineApiKey` 后，在开发机执行：

```bash
cd desktop
make build
bin/agentteam daemon --connect agentteam --agentteam.server-url https://agentteam.pingcap.com --agentteam.api-key <machineApiKey>
```

machine online 后创建 agent 并发消息验证链路。

---

## 8. 回滚

代码回滚（推荐）：

```bash
ssh root@10.2.103.216
cd /opt/agentteam

sudo -u agentteam git -C /opt/agentteam log --oneline -n 20
sudo -u agentteam git -C /opt/agentteam reset --hard <稳定版本commit>

bash scripts/deploy-main.sh
```

配置回滚（如有备份）：

```bash
cp /etc/agentteam/agentteam.env.bak.<timestamp> /etc/agentteam/agentteam.env
systemctl restart agentteam-server
```

跨越 standalone → unified 边界的回滚必须使用同一 release ID 的配置备份，并恢复完整旧 release bundle 中的 binary/image、manifest、systemd service、路由和 worker ownership。只切换 `/opt/agentteam/current` 或只恢复旧 binary 不构成可用回滚；旧 standalone release 需要其配套的 MeshX discovery 配置与第二 resident owner。