Files
ai-soulmate-local-deployment/docs/CROSS-COMPUTER-HANDOFF.md
T

186 lines
8.0 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.
# AI SoulMate 本地部署跨电脑交接说明
## 2026-08-05 本次接管更新
- 已在服务器完成脱敏硬件采集并更新 [`POC-HARDWARE-BASELINE.md`](POC-HARDWARE-BASELINE.md):NVMe 当前无健康告警,但记录到 14 次非正常关机;网卡链路已连接,实际速率和整机温度仍待补采。
- 已从用户提供的压缩包恢复部署仓库;压缩包中的 Git 此前没有 commit 和远端,本次已完成重建与归档。
- 已新增 Ubuntu 22.04 运行手册、源码版本核对说明、Docker 官方仓库安装脚本、随机密钥生成脚本和源码基线采集脚本。
- 已新增 PostgreSQL、Redis、MinIO 基础设施 POC Compose;三个宿主机端口只绑定到 127.0.0.1,并带持久化、健康检查、资源上限和日志轮换。
- 接管前当前工作区只有另一个指向 Gitee/Spring Boot 的 ai-soulmate-server 本地仓库,不能作为内部 FastAPI 仓库的发布基线。
- 已只读核对并浅克隆四个内部远端:server develop6@9a6f7a5、client master@9ebb082、admin main@40bd686、nginx master@6f552f4;server/client 与旧交接基线不同。
- server 默认分支使用 Hunyuan3D/Bailian 而不是需求描述的 Tripo,因此发布分支选择仍是业务改造前的阻断项。
- 四个仓库存在被 Git 跟踪的非示例环境文件,server 还含支付/私钥类值;所有相关凭据必须先轮换,具体值未复制到部署仓库。
- 内部 server 当前 Compose 使用 Uvicorn/Vite 开发模式、源码 bind mount 和开放的数据库/Redis 端口,不能直接作为交付版本。
- 下一安全动作是完成系统安全更新并按需重启,补采链路速率和温度,再安装 Docker;之后重新克隆四个源码仓库并生成 source-check 报告。
- 已创建首次 Git commit 9e2196d,并推送到 MLKJ/ai-soulmate-local-deployment 的 main 分支。
更新时间:2026-08-05
这份文档用于在另一台电脑继续本地部署适配。它记录事实、已完成事项和下一步顺序;不要把文档中的示例 IP、密码或 API Key 当成生产配置。
## 一句话状态
服务器已经可以通过 SSH 访问,但业务系统尚未部署;部署仓库已经完成首次提交并推送到 Gitea,换电脑或服务器接管时直接克隆该私有仓库。
## 已确认事实
### 服务器
- Ubuntu 22.04.5 LTS,x86_64,内核 5.19.0-32-generic;登录提示有 13 个待应用更新,其中 11 个为标准安全更新。
- 网卡 `enp1s0` 已拿到 `192.168.3.102`,SSH 已成功连接。
- `openssh-server` 已安装并可以连接。
- `ufw status verbose` 显示 `inactive`,目前没有 UFW 规则阻断 SSH。
- 尚未确认 SSH 公钥登录是否完成;尚未关闭密码登录。
- 尚未完成系统更新、Docker、Compose、PostgreSQL、Redis、对象存储和网关部署。
- 应在路由器或网络设备上为服务器做 DHCP 地址保留,避免重启后 IP 变化。
### 样机硬件
- HP ZCentral 4R Workstation。
- Intel Xeon W-2225,4 核 8 线程。
- 32GiB ECC DDR4,单条内存,约 1TB 单块 Samsung NVMe。
- Swap 2GiB,单盘无冗余;NVMe 当前无关键、寿命或介质错误告警,但有 14 次非正常关机记录。
- 适合 POC、适配和容量边界测试,不可直接作为生产高可用承诺。
- 完整评估见 [`POC-HARDWARE-BASELINE.md`](POC-HARDWARE-BASELINE.md)。
### 源码版本基线
| 仓库 | 当前提交 |
| --- | --- |
| `ai-soulmate-server` | `24769465d3ac2cb840c5266c8c0def2aacb641aa` |
| `ai-soulmate-client` | `170847159a787c7b52e3f9f792d72ea67cbd7fa4` |
| `mlkj-admin` | `40bd686128010fbbc6c33f6156a7a3cda5336b3a` |
| `nginx-server` | `6f552f4b37505ec055cdd179fe9cc5a6825a4189`,仅做过远端检查 |
完整清单见 [`inventory/source-baselines.yml`](../inventory/source-baselines.yml)。
## 当前部署目标
中心服务器先运行:
```text
统一网关 → 平台前端 / AI SoulMate 管理端 → 平台后端
├→ PostgreSQL
├→ Redis
├→ 本地 S3 兼容对象存储
└→ Tripo 外部 API
```
后续农场工作站运行 `ai-soulmate-client`,通过 HTTPS 心跳、拉取任务和上报状态,不把打印机直接暴露给中心服务器。
Tripo 当前仍是外部 API,因此目标是本地化业务平台和数据基础设施,不是当前阶段的完全离线部署。
## 换电脑时重建 Git 仓库
### 推荐:复制现有部署目录
把当前电脑的整个目录复制到新电脑,包含未提交文件但不需要复制 `.git`:
```text
/Users/max/AI SoulMate/开发/ai-soulmate-local-deployment
```
在新电脑进入目录后检查:
```bash
git status
git branch --show-current
```
如果没有 `.git`,重新初始化:
```bash
git init -b main
```
### 需要长期留档时
先在 Gitea 创建一个空的私有仓库,例如 `MLKJ/ai-soulmate-local-deployment`,再在新电脑执行:
```bash
git add .
git commit -m "chore: initialize local deployment baseline"
git remote add origin <GITEA_REPOSITORY_URL>
git push -u origin main
```
远端 URL、账号和访问令牌不要写入文档或 `.env`。如果部署目录没有复制过来,必须先恢复本目录中的 `README.md`、`docs/`、`inventory/`、`benchmark/`、`scripts/`、`compose/` 和 `decisions/`,再执行上述提交。
## 新电脑接管顺序
### A. 先固定 SSH 访问
在新电脑生成或准备 SSH 密钥,把公钥加入服务器 `hp` 用户:
```bash
ssh-keygen -t ed25519 -a 64 -f ~/.ssh/id_ed25519_ai_soulmate
cat ~/.ssh/id_ed25519_ai_soulmate.pub | ssh hp@192.168.3.102 \
'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'
```
确认密钥登录成功后,才考虑关闭密码登录。修改 SSH 配置前保留当前会话,并先用 `sudo sshd -t` 检查配置。
### B. 记录并更新服务器
在服务器上执行:
```bash
whoami
hostnamectl
ip -br addr
sudo systemctl is-active ssh
df -hT /
free -h
lscpu
sudo timedatectl set-timezone Asia/Shanghai
sudo apt update
sudo apt install -y git curl ca-certificates gnupg jq unzip rsync tmux htop nvme-cli smartmontools
sudo apt upgrade -y
```
如果出现 `/var/run/reboot-required`,记录后再重启,并重新确认服务器 IP。
### C. 安装容器运行时
使用 Docker 官方 Ubuntu 仓库安装 Docker Engine、Buildx 和 Compose plugin。安装前确认网络、DNS、NTP 和磁盘空间;不要使用来源不明的一键安装脚本。
安装后至少验证:
```bash
docker version
docker compose version
sudo systemctl is-active docker
```
### D. 再开始业务改造
不要直接把当前四个仓库用现有 Compose 上线。必须先完成:
1. 平台后端和管理端的 OSS provider 抽象,并验证本地 S3 兼容对象存储。
2. 管理端 `ai-soulmate-only` 模式,避免强制连接其他业务数据库。
3. 生产前端构建和不可变镜像,去除源码 bind mount。
4. 初始化/迁移、备份/恢复、健康检查和密钥注入。
5. 网关路由、TLS、上传限制和管理入口隔离。
具体路线见 [`IMPLEMENTATION-ROADMAP.md`](IMPLEMENTATION-ROADMAP.md),压测规则见 [`BENCHMARK-PLAN.md`](BENCHMARK-PLAN.md)。
## 不要做的事情
- 不要把 SSH、PostgreSQL、Redis 或对象存储管理端口暴露到公网。
- 不要把真实密码、Tripo Key、OSS Key、证书或客户数据提交到 Git。
- 不要把 Tripo 的端到端延迟直接当作本地服务器并发能力。
- 不要在单盘、32GB POC 样机上直接承诺生产高可用或客户 SLA。
- 不要在没有备份恢复演练前导入唯一生产数据。
## 接管清单
- [ ] 新电脑已恢复部署仓库目录。
- [x] Git 仓库已初始化并完成首次提交。
- [x] 已创建私有远端并推送 `main`。
- [ ] Mac/新电脑使用密钥登录服务器。
- [ ] 服务器 IP 已固定或完成 DHCP 保留。
- [ ] 已完成系统更新和硬件基线采集。
- [ ] 已安装并验证 Docker Compose。
- [ ] 已完成 P1/P2 源码改造后再创建正式 Compose。