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

112 lines
5.2 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.
# Ubuntu 22.04 本地部署运行手册
这台 HP ZCentral 4R 是 POC 和适配样机。当前目标是跑通中心服务、管理端、PostgreSQL、Redis、本地对象存储和 Tripo 出站调用;它不是生产高可用承诺。
## 0. 先确认网络和 SSH
在服务器本地控制台或当前 SSH 会话记录:
~~~bash
hostnamectl
nmcli device status
ip -br addr
sudo systemctl is-active ssh
df -hT /
free -h
~~~
在路由器上为有线网卡做 DHCP reservation,或者使用网络管理员批准的静态地址。不要凭 enp1s0、eno1 这样的示例名修改连接。保留当前密码 SSH 会话,直到另一台电脑用 Ed25519 密钥成功登录。
## 1. 固化主机基线
~~~bash
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 和工具
~~~bash
cd /srv/ai-soulmate-local-deployment
sudo TIMEZONE_NAME=Asia/Shanghai RUN_UPGRADE=1 \
./scripts/bootstrap-ubuntu-22.04.sh
~~~
脚本使用 Docker 官方 apt 仓库,不修改网络地址、不自动打开防火墙端口,也不会替代现场重启决策。若出现 /var/run/reboot-required,先记下结果,再重启并重新确认 IP、SSH、磁盘和 Docker。
## 3. 放置并核对源码
源码与部署仓库分开,例如:
~~~bash
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 后再继续。
~~~bash
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. 先启动基础设施
~~~bash
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 留档
~~~bash
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。