Files
ai-soulmate-local-deployment/docs/DEPLOYMENT-RUNBOOK.md
T

5.2 KiB
Raw Blame History

Ubuntu 22.04 本地部署运行手册

这台 HP ZCentral 4R 是 POC 和适配样机。当前目标是跑通中心服务、管理端、PostgreSQL、Redis、本地对象存储和 Tripo 出站调用;它不是生产高可用承诺。

0. 先确认网络和 SSH

在服务器本地控制台或当前 SSH 会话记录:

hostnamectl
nmcli device status
ip -br addr
sudo systemctl is-active ssh
df -hT /
free -h

在路由器上为有线网卡做 DHCP reservation,或者使用网络管理员批准的静态地址。不要凭 enp1s0、eno1 这样的示例名修改连接。保留当前密码 SSH 会话,直到另一台电脑用 Ed25519 密钥成功登录。

1. 固化主机基线

cd /srv/ai-soulmate-local-deployment
chmod +x scripts/*.sh
./scripts/collect-host-facts.sh \
  > results/raw/host-facts-$(date +%Y%m%d-%H%M%S).txt

原始文件默认不进 Git。审阅后只把脱敏结论写入 results/reports/,不要记录 IP、MAC、序列号、UUID 或客户数据。

2. 安装 Docker 和工具

cd /srv/ai-soulmate-local-deployment
sudo TIMEZONE_NAME=Asia/Shanghai RUN_UPGRADE=1 \
  ./scripts/bootstrap-ubuntu-22.04.sh

脚本使用 Docker 官方 apt 仓库,默认强制 IPv4、重试下载并校验官方 GPG 指纹;不修改网络地址、不自动打开防火墙端口,也不会替代现场重启决策。若出现 /var/run/reboot-required,先记下结果,再重启并重新确认 IP、SSH、磁盘和 Docker。

3. 放置并核对源码

源码与部署仓库分开,例如:

sudo mkdir -p /srv/ai-soulmate/sources
sudo chown -R "$USER":"$USER" /srv/ai-soulmate
cd /srv/ai-soulmate/sources
git clone http://39.106.119.229:3000/MLKJ/ai-soulmate-server
git clone http://39.106.119.229:3000/MLKJ/ai-soulmate-client
git clone http://39.106.119.229:3000/MLKJ/mlkj-admin
git clone http://39.106.119.229:3000/MLKJ/nginx-server

如果仓库已经存在,不要直接覆盖用户改动;逐个执行 git status --short、git remote -v 和 git rev-parse HEAD。完成后生成核对报告:

截至 2026-08-05,server 默认分支是 develop6,但其 AI provider 与需求描述不一致;client 的旧交接 SHA 也不是默认分支 HEAD。克隆完成不代表发布分支已经选定,必须由仓库负责人确认 release branch/tag 后再继续。

cd /srv/ai-soulmate-local-deployment
SOURCE_ROOT=/srv/ai-soulmate/sources \
  ./scripts/record-source-baseline.sh \
  > inventory/source-check-$(date +%F-%H%M%S).yml

4. 先启动基础设施

cd /srv/ai-soulmate-local-deployment
./scripts/create-local-env.sh compose/.env
docker compose --env-file compose/.env \
  -f compose/docker-compose.infra.yml config
docker compose --env-file compose/.env \
  -f compose/docker-compose.infra.yml pull
docker compose --env-file compose/.env \
  -f compose/docker-compose.infra.yml up -d
docker compose --env-file compose/.env \
  -f compose/docker-compose.infra.yml ps
./scripts/verify-infra.sh compose/.env

PostgreSQL、Redis 和 MinIO 只绑定到 127.0.0.1。未来业务容器使用 postgres:5432、redis:6379 和 minio:9000,不要把 .env 中的宿主机端口当作容器间地址。MinIO 控制台需要时使用 SSH 隧道,不开放公网管理端口。

5. 业务部署门槛

当前 ai-soulmate-server 的 Dockerfile 只有开发目标,开发 Compose 还挂载源码;压缩包中的 ai-soulmate-server-master 没有可验证的 Git 历史。先完成以下改造,再写应用 Compose:

  1. 平台和管理端引入统一对象存储接口,同时保留 Alibaba OSS provider,并让 MinIO 等本地 S3 provider 通过预签名上传、下载、分片、CORS、权限、元数据和恢复测试。
  2. mlkj-admin 增加 AI SoulMate-only profile,不能初始化无关业务库、默认账号或固定密码。
  3. 为后端、平台前端和管理端生成生产镜像;禁止源码 bind mount,固定基础镜像版本并记录 digest。
  4. 添加迁移、健康检查、资源上限、日志轮换、备份恢复和回滚流程。
  5. 再决定是否使用 nginx-server。它只承担环境无关的 TLS、路由、上传限制、访问日志和限流;若现场已有企业网关,优先复用企业网关。

6. 验收顺序

按 S01 到 S07 的场景逐级验收:健康检查和登录 → 管理端查询 → 对象上传下载 → 任务创建与轮询 → Tripo 出站 → 混合负载 → 工作站任务下发。Tripo 的提交、轮询、下载、外部排队和限流时间必须单独记录,不能作为本地并发能力。

每次压测使用固定数据集和请求比例,从并发 1, 2, 5, 10, 15, 20... 逐级增加;每个稳定档位至少重复三次,保存元数据、脱敏报告和原始日志位置。出现 OOM、持续 swap、容器重启、数据错误、队列增长或外部 API 限流时停止加压。

7. Git 留档

git clone \
  http://39.106.119.229:3000/MLKJ/ai-soulmate-local-deployment \
  /srv/ai-soulmate-local-deployment
cd /srv/ai-soulmate-local-deployment
git log -1 --oneline
git remote -v

远端私有仓库已经建立,main 已完成首次推送。后续每次部署改动都要先更新交接记录和版本清单,再提交并推送。不要把账号密码、访问令牌或真实 .env 写进 URL、文档或 Git。