Files
moyi-model-intelligence-hub/docs/11-server-test-deployment.md
T

192 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 北京测试服务器部署手册
## 1. 已确认的环境与本次边界
| 项目 | 本次配置 |
| --- | --- |
| 应用服务器 | 阿里云轻量,北京,4 核 8 GiB,Ubuntu 24.04,70 GiB 系统盘 |
| 公网地址 | `39.96.90.106` |
| 私网地址 | 截图为 `172.17.24.125`;配置内网互通后再次核对 |
| 域名 | `moyi.soulofmodel.com`,不修改 `www` 或主域名原系统 |
| 数据库 | 现有北京 RDS PostgreSQL 15,新增独立数据库 `moyi_control` |
| 缓存 | 现有北京 Tair 标准架构,专用账号及 `moyi:test:` Key 前缀 |
| 对象存储 | 北京 OSS 可预留新 Bucket,本次 Java 部署暂不需要 OSS 密钥 |
这是内部测试发布,不是完整生产版。可验收登录、邀请码、目录、项目、Key 权限、非流式同步转发、限流、模型并发和调用审计。以下尚未完成:Java 真实 Tripo/Seedance 异步执行、OSS 文件保存、流式转发、完整计费扣减、分布式任务抢占和可靠重试。
真实供应商没有配置密钥时返回 503,不再返回 Mock 成功。只有明确绑定 `provider-mock` 的模型可以走 Mock;真实异步供应商返回 501。已有种子目录和价格只是联调数据,实际模型 ID/能力须由供应商控制台核验后修改。
注意更正早期说明:当前登录会话和任务状态保存于 PostgreSQL;Tair 已实现的是按 Key 限流、按模型并发租约,不是已完成的 MQ、幂等或异步调度平台。不需要现在购买 MQ。
## 2. 你需要在阿里云完成的配置
### 网络互通,先确认对旧系统的影响
1. 确认新服务器、RDS、Tair 在同一阿里云账号和北京地域。
2. 轻量控制台的“内网互通”中关联 RDS/Tair 所属 VPC;如属于不同 VPC,分别设置。
3. **首次在该地域开通内网互通可能导致该地域所有轻量服务器停机约 1 分钟**,包括现有小程序服务器。先检查是否已开通,在维护时间执行,不要为本项目随意取消旧连接。
4. 开通后重新核对新服务器私网 IP,把它以 `/32` 加入 RDS、Tair 的新增白名单分组 `moyi-test`。保留旧系统的白名单,不要覆盖或放行 `0.0.0.0/0`。
5. 不要为了连接方便给 RDS/Tair 开公网地址;同地域不等于已内网互通。
依据:[阿里云轻量内网互通](https://help.aliyun.com/zh/simple-application-server/user-guide/manage-service-interconnection/)。
### 防火墙和网段
- SSH 22 仅允许办公公网 IP;先保持当前会话并验证新登录通路,再收紧来源,避免锁出。
- SSH 隧道模式不需要开放 80/443/8080。HTTPS 模式开放 80、443;内部测试阶段建议也仅允许测试人员公网 IP。
- Java 8787、数据库端口、6379 不发布到公网;8080 始终只绑定 `127.0.0.1`。
- 不只依赖 UFW:Docker 发布端口的流量可能绕过 UFW,阿里云防火墙来源限制必须配置。[Docker 官方说明](https://docs.docker.com/engine/install/ubuntu/)
- 当前服务器在 `172.17.*` 私网,而 Docker 默认桥接网络也可能使用 `172.17.0.0/16`。安装前后查看 `ip route`;若重叠,先调整 Docker 地址池/默认桥接网段,再启动。不要直接覆盖已有 `/etc/docker/daemon.json`。
- 本 Compose 显式使用 `10.253.240.0/24`,但这只是待确认候选值。须确保不与服务器、RDS、Tair、现有 Docker/VPC 路由重叠;必要时修改 `MOYI_DOCKER_SUBNET`。脚本会检查该子网与已解析的 RDS/Tair 地址是否重叠,不代替完整路由审查。
### RDS PostgreSQL 15
1. 在现有 RDS 实例创建专用数据库 `moyi_control` 和专用账号 `moyi_app`,**不在小程序库里直接添加本项目的表**。
2. 确保 `moyi_app` 在这个库中有连接、建表、建索引和读写权限。PG15 中需确认 `public` schema 的 CREATE 权限或让该账号拥有新库;不能只授予 SELECT/INSERT。
3. 新数据库第一次启动由 Flyway 自动建表。配置关闭自动 baseline,非空未受 Flyway 管理的库会拒绝迁移,不要为绕过错误而启用 baseline。
4. 数据库修改前创建 RDS 备份,并核对可恢复性;不调整原系统账号、权限或数据库。
5. 提供内网地址、实际端口、库名和账号。密码只填写服务器 `.env.cloud`。若启用数据库 TLS,按 RDS 配置 JDBC 参数及 CA 校验,不默认假设端口/TLS。
### Tair 标准架构
1. 新建本项目专用账号,保留旧系统账号与密码。不要重置共享实例的默认密码。
2. 使用内网地址、标准架构连接,按实例实际情况填写 TLS、端口、账号和密码。
3. 无需创建表。使用 `moyi:test:` 前缀;支持 ACL Key 规则时,限制为此命名空间。可使用受支持的独立逻辑 DB,但它不等于独立实例或资源隔离。
4. 网关需要 PING、Lua 脚本执行以及 INCR、PTTL、PEXPIRE、TIME、ZADD、ZCARD、ZREM、ZREMRANGEBYSCORE 等操作。只读账号不够。预检查仅验证 TCP,应用就绪检查再验证连接与鉴权,Mock 模型调用才验证真实 Lua 权限。
5. **不要执行 FLUSHDB、FLUSHALL,不要修改共享实例的全局配置。** 共享实例的内存、CPU、驱逐策略仍共享,测试流量要有限额。
### 域名和 DV 证书
1. 在 `soulofmodel.com` 的当前 DNS 托管处添加 A 记录:主机记录 `moyi`,值 `39.96.90.106`,TTL 默认 10 分钟。不修改 `www`、`@`、MX 或 DNS 服务器。
2. 申请覆盖 **`moyi.soulofmodel.com`** 的单域名 DV 证书即可。DV 满足当前企业测试的 HTTPS 需求,OV/EV 主要增加组织身份核验,不是当前必需项。[阿里云选型说明](https://help.aliyun.com/zh/ssl-certificate/functions-and-features)
3. 使用证书控制台给出的 DNS 验证记录,不删除原业务验证记录;下载 **Nginx 格式**证书。
4. 将包含完整链的 PEM 和对应私钥放到服务器 `infra/moyi/certs/fullchain.pem`、`privkey.pem`,私钥权限 600。不要发到聊天或 Git。
5. 现有域名已备案并接入阿里云时,子域名通常无需单独备案;仍需核对主体、服务内容和页面备案信息。备案不是模型供应商授权或 AI 服务合规的替代。[子域名备案说明](https://help.aliyun.com/zh/icp-filing/basic-icp-service/support/for-the-record-domain-faq/)
### OSS 本次可以后置
可先创建北京私有 Bucket,例如自定义的 `moyi-test-assets-*`;名称须全局唯一。Java 的结果文件落盘尚未完成,本次不需要创建或提供 AccessKey,更不要为赶部署设置公共读写。后续接入时再配置仅目标 Bucket 的 RAM 权限、签名 URL、生命周期和测试/生产隔离。
## 3. 部署包与服务器初始化
发布压缩包位于开发机 `artifacts/moyi-test-<版本>.tar.gz`,旁边有 `.sha256`。包内包含已编译的 Java 21 JAR、Vue 静态文件、运行时 Dockerfile、Compose、环境变量模板、Nginx、部署脚本和逐文件校验清单。
它不是离线 Docker 镜像包。服务器不用安装 Java/Maven/Node,但首次需访问镜像仓库下载 `eclipse-temurin:21-jre-alpine` 和 `nginx:1.27-alpine`。若网络不可用,应由开发机/CI 构建并推送阿里云 ACR 或交付 `docker save` 镜像包;不要使用来源不明的镜像代理。运行时镜像地址可以通过环境模板改为已同步的可信镜像地址。
将压缩包及 SHA256 文件通过 SCP/SFTP 上传到服务器同一目录。下面操作在服务器执行;`<版本>` 替换成实际文件名中的版本:
```bash
sha256sum -c moyi-test-<版本>.tar.gz.sha256
sudo mkdir -p /opt/moyi/releases/<版本>
sudo tar -xzf moyi-test-<版本>.tar.gz -C /opt/moyi/releases/<版本>
cd /opt/moyi/releases/<版本>/infra/moyi
sudo bash install-docker-ubuntu.sh
sudo python3 deploy.py verify
sudo python3 deploy.py init
sudo nano .env.cloud
```
安装脚本仅针对 Ubuntu 24.04,使用 Docker 官方 APT 源。发现已有 Docker 时不覆盖安装;发现冲突包时停止,不自动卸载。仓库不可达时报错停止,再单独配置可信来源,不会关闭 TLS 校验。不要为执行安装脚本更改现有服务器上的 Nginx、UFW 或其他应用。
`init` 自动生成随机管理员初始密码、密码 Pepper 和供应商凭证加密密钥,配置文件权限 600;已存在配置时拒绝覆盖。账号仍是已约定的 `adimin`,**云端不使用 `admin123`**。初始密码在服务器 `.env.cloud` 中查看,不会打印到日志。
## 4. 环境变量怎么填
| 分类 | 变量 | 本次要求 |
| --- | --- | --- |
| RDS | `MOYI_DB_URL`、`MOYI_DB_USERNAME`、`MOYI_DB_PASSWORD` | 必填;新建 PostgreSQL 数据库 |
| Tair | `MOYI_REDIS_HOST/PORT/USERNAME/PASSWORD/DATABASE/SSL` | 地址、密码必填,其他按实例信息 |
| 隔离 | `MOYI_REDIS_KEY_PREFIX`、`MOYI_DOCKER_SUBNET` | 专用前缀,网段不冲突 |
| 安全 | `AUTH_PASSWORD_PEPPER`、`CREDENTIAL_ENCRYPTION_KEY`、`ADMIN_PASSWORD` | init 已生成;升级必须保留 |
| HTTPS | `MOYI_DOMAIN` | 已预填 `moyi.soulofmodel.com`;证书另放 certs |
| 容量 | `DB_POOL_*`、`GATEWAY_*`、`TASK_*`、`JAVA_OPTS` | 先用测试默认值,不代表已压测容量 |
| 供应商 | `DEEPSEEK_*`、`KIMI_*`、`ZHIPU_*` | 首次可空,在管理端配置更直观;环境密钥优先级更高 |
| 后置 | `OSS_*`、`TRIPO_API_KEY`、`VOLCENGINE_API_KEY` | 预留,不注入本次 Java 服务,留空 |
密码包含 `$`、`#` 或空格时用单引号包住,例如 `MOYI_REDIS_PASSWORD='实际密码'`。若密码本身包含单引号,按 Compose dotenv 转义规则处理。**不要 `source .env.cloud`,不要把完整 `docker compose config` 输出发到聊天**,其中可能含真实密钥。使用 `deploy.py check` 只输出检查结论。
旧的 `MOYI_REDIS_URL` 已改为分离字段,避免用户名/密码的 URL 编码问题。旧云配置升级时逐项补齐,不直接复制覆盖。Cookie 安全属性由模式决定,不再通过随意设置公网 HTTP 来降低安全性。
## 5. 启动方式二选一
### A. 暂无证书:SSH 隧道内部测试
```bash
sudo python3 deploy.py check --mode tunnel --network
sudo python3 deploy.py up --mode tunnel --accept-migrations
sudo python3 deploy.py smoke --mode tunnel --login
```
在你自己的电脑打开一个终端并保持连接(替换 `SSH用户名`,不要默认假设是 root):
```powershell
ssh -N -L 8080:127.0.0.1:8080 SSH用户名@39.96.90.106
```
浏览器访问 `http://localhost:8080`。无需开放公网 8080,登录流量通过 SSH 加密。若电脑 8080 已占用,应同时调整配置中的本地端口和 CORS,或选择另一个转发端口后同步 CORS。
### B. 域名和证书就绪:HTTPS 测试
```bash
sudo chmod 600 certs/privkey.pem
sudo python3 deploy.py check --mode https --network
sudo python3 deploy.py up --mode https --accept-migrations
sudo python3 deploy.py smoke --mode https --login
```
通过阿里云防火墙允许的测试人员访问 `https://moyi.soulofmodel.com`,模型 API 使用 `https://moyi.soulofmodel.com/v1`。HTTPS 模式自动开启 Secure Cookie;证书错误时拒绝启动。不要关闭客户端证书校验。
`up` 先编译运行时镜像,再启动后端、检查 RDS/Tair 就绪、校验 Nginx,最后启动前端。数据库迁移必须明确带 `--accept-migrations`;配置错指其他库仍可能造成改动,执行前须核对并备份。后端不会对公网发布端口。
## 6. 查看状态、测试与排障
```bash
sudo python3 deploy.py status
sudo python3 deploy.py logs
sudo python3 deploy.py smoke
sudo python3 deploy.py stop
```
成功启动后会保存模式,后续命令默认沿用;第一次启动失败时请显式带 `--mode`。`stop` 只停止容器,不删数据库、缓存或镜像。
验收顺序:
1. 登录与退出、刷新恢复会话;管理员创建邀请码,普通用户注册。
2. 创建个人/项目 Key,编辑模型权限,禁用 Key 后访问被拒绝。
3. 用明确标记 Mock 的文本模型检查 Tair Lua 限流和并发,再配置一个真实同步供应商、小额验证请求与响应。
4. 查看调用记录输入输出、错误、按 Key 筛选及导出;测试数据也可能含个人信息,仅管理员可访问,注意日志留存与脱敏。
5. Java 流式调用仍返回 501;真实 3D/视频接口仍返回 501,不属于本次可用能力。
`smoke` 默认不调用任何付费模型;`--login` 会使用初始管理员凭据验证 Cookie 并产生登录审计。如已修改管理员密码,不再使用初始凭据进行该测试。
常见失败:
- RDS/Tair TCP 不通:检查 VPC 内网互通、私网 IP、白名单和网段冲突;不要改成全网白名单。
- 后端 unhealthy:通过 logs 检查数据库账号权限、Flyway、Tair TLS/密码。`/health` 是基本状态,容器就绪依据 `/actuator/health/readiness`,外部不能访问 actuator。
- 镜像下载失败:检查服务器到官方镜像仓库的连接,下一步交付 ACR/离线镜像;不要重复更换应用端口。
- 页面能开但登录失败:检查所用模式和浏览器域名,HTTPS 模式不能用 IP HTTP 登录。
- 真实模型 503:先在管理端配置正确供应商 Key、Base URL、上游模型 ID,不是服务器配置不足。
## 7. 证书更新、升级与回退
本包提供有效期检查及安全重载,**不自动购买、签发或续期证书**。开启阿里云证书到期通知,续签后替换服务器 `certs/fullchain.pem`、`privkey.pem`,执行:
```bash
sudo python3 deploy.py check --mode https
sudo python3 deploy.py reload-tls --mode https
```
检查会提示 30 天内到期,证书不足 1 天有效期时拒绝;`nginx -t` 成功后才 reload。保留旧证书备份以便更新失败时恢复。
升级时每个版本解压到独立 `releases/<版本>` 目录,**保留相同 Compose 项目名**,安全复制旧 `.env.cloud` 和证书到新版本,并补齐新增配置项。不要重新生成 Pepper/加密密钥,否则会影响密码校验和供应商凭据解密。预编译发布包需将旧环境中的 `MOYI_IMAGE_TAG` 改为新 `release-manifest.json` 的 `release` 值,并使用 `Dockerfile.runtime`。
执行新版本 `check`、备份 RDS 后再 `up`。构建失败时旧容器仍运行;数据库迁移及后端更新后发生的失败不能承诺自动回退。只有确认旧程序与新数据库结构兼容,才能回到旧版本目录用相同项目名启动;不兼容时需从 RDS 备份恢复到另一个测试库并重新验证。禁止用 `docker system prune`、`down -v`、删除旧库等方式“修复”发布失败。
## 8. 还需提供的信息
- RDS 内网地址、端口、新库和账号名、所属 VPC;Tair 内网地址、端口、账号、TLS 状态及 VPC。
- DNS A 记录是否完成,DV 证书是否已签发并上传到服务器。
- SSH 登录用户名、端口以及你已配置的密钥连接方式;不要发送密码或私钥。
密码/模型 Key 只由你填写 `.env.cloud` 或管理端。未获得这些信息和服务器访问授权前,本包只能在本机完成构建与配置测试,不能宣称已部署到云服务器。