136 lines
7.3 KiB
Markdown
136 lines
7.3 KiB
Markdown
# 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. 业务部署门槛
|
||
|
||
当前 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。
|