# 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 仓库,默认只对密钥下载强制 IPv4、重试下载并校验官方 GPG 指纹;APT 保持系统网络策略,避免影响现有 Ubuntu 镜像源。不修改网络地址、不自动打开防火墙端口,也不会替代现场重启决策。若出现 /var/run/reboot-required,先记下结果,再重启并重新确认 IP、SSH、磁盘和 Docker。 若 `docker run --rm hello-world` 在访问 `registry-1.docker.io` 时超时,先确认现场批准使用的镜像代理,再配置 Docker。当前 POC 使用 DaoCloud 公共镜像代理;它只用于解决联网适配,不替代生产环境的私有镜像仓库: ~~~bash 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. 放置并核对源码 源码与部署仓库分开,例如: ~~~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 隧道,不开放公网管理端口。 首次通过健康检查后,执行 `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,完成后自动清理: ~~~bash 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`。后端先绑定回环地址,数据库和 Redis 不向局域网开放;MinIO API 只绑定批准的局域网地址,控制台保持回环绑定。 平台后端已有独立镜像、无源码挂载的 Compose、资源上限、日志轮换、健康检查和 MinIO provider。继续完成以下业务门槛: 1. 验证 MinIO 预签名上传、下载、浏览器 CORS、权限和备份恢复。 2. 为平台前端生成生产镜像,并与本地后端完成登录和核心业务联调。 3. 为 mlkj-admin 增加 AI SoulMate-only profile,不能初始化无关业务库、默认账号或固定密码。 4. 固定后端、平台前端和管理端基础镜像版本,记录最终镜像 digest 和回滚版本。 5. 部署环境无关的统一网关,或接入客户已有企业网关,由其承担 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。