Files

138 lines
7.3 KiB
Markdown
Raw Permalink 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 仓库,默认只对密钥下载强制 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`,平台前端见 `docs/FRONTEND-DEPLOYMENT.md`。后端先绑定回环地址,数据库和 Redis 不向局域网开放;前端和 MinIO API 只绑定批准的局域网地址,MinIO 控制台保持回环绑定。
平台后端已有独立镜像、无源码挂载的 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。