7.3 KiB
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 指纹;APT 保持系统网络策略,避免影响现有 Ubuntu 镜像源。不修改网络地址、不自动打开防火墙端口,也不会替代现场重启决策。若出现 /var/run/reboot-required,先记下结果,再重启并重新确认 IP、SSH、磁盘和 Docker。
若 docker run --rm hello-world 在访问 registry-1.docker.io 时超时,先确认现场批准使用的镜像代理,再配置 Docker。当前 POC 使用 DaoCloud 公共镜像代理;它只用于解决联网适配,不替代生产环境的私有镜像仓库:
cd /srv/ai-soulmate-local-deployment
DOCKER_REGISTRY_MIRROR=https://docker.m.daocloud.io \
./scripts/configure-docker-registry-mirror.sh
docker run --rm hello-world
脚本会保留 /etc/docker/daemon.json 中的其他设置、校验新配置、备份旧文件并重启 Docker。已有业务容器时,必须先安排 Docker 重启窗口。正式交付应使用客户可控的镜像仓库,并按 inventory/ 中记录的 digest 固定镜像内容。
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 隧道,不开放公网管理端口。
首次通过健康检查后,执行 scripts/capture-runtime-snapshot.sh 保存空载资源基线,并用 docker image inspect 将实际拉取到的镜像 digest 写入脱敏的 inventory/ 清单。原始快照继续保留在服务器的 results/raw/,不要提交主机标识、凭据或客户数据。
基础设施备份默认写入 Git 忽略的 results/backups/infra/。备份包含 PostgreSQL 逻辑备份、Redis RDB 和 MinIO Bucket 对象,不复制 .env。创建后立即执行隔离恢复校验;该校验会恢复到临时 PostgreSQL 数据库和临时 MinIO Bucket,完成后自动清理:
backup_output="$(./scripts/backup-infra.sh compose/.env)"
printf '%s\n' "$backup_output"
backup_directory="$(printf '%s\n' "$backup_output" | sed -n 's/^Infrastructure backup created: //p')"
./scripts/verify-infra-backup.sh compose/.env "$backup_directory"
本机备份不能替代异机备份。验证通过后,将整个时间戳目录复制到单独管理的磁盘或备份服务器,并在交付前补充保留周期、加密、访问审计和定期恢复演练。当前 MinIO 备份覆盖 Bucket 中的对象;若后续启用版本控制、生命周期、复制、IAM 或自定义策略,还必须增加相应配置导出和恢复步骤。
5. 业务部署门槛
后端本地容器的配置、构建、启动和连接验收见 docs/BACKEND-DEPLOYMENT.md,平台前端见 docs/FRONTEND-DEPLOYMENT.md。后端先绑定回环地址,数据库和 Redis 不向局域网开放;前端和 MinIO API 只绑定批准的局域网地址,MinIO 控制台保持回环绑定。
平台后端已有独立镜像、无源码挂载的 Compose、资源上限、日志轮换、健康检查和 MinIO provider。继续完成以下业务门槛:
- 验证 MinIO 预签名上传、下载、浏览器 CORS、权限和备份恢复。
- 为平台前端生成生产镜像,并与本地后端完成登录和核心业务联调。
- 为 mlkj-admin 增加 AI SoulMate-only profile,不能初始化无关业务库、默认账号或固定密码。
- 固定后端、平台前端和管理端基础镜像版本,记录最终镜像 digest 和回滚版本。
- 部署环境无关的统一网关,或接入客户已有企业网关,由其承担 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。