feat: add reproducible backend deployment

This commit is contained in:
wlx committed 2026-08-07 12:39:15 +08:00
1 parent 6190e58511
commit ac0d3856f0
11 files changed
+431 -16

No files matched your search

+64
View File
@@ -0,0 +1,64 @@
# AI SoulMate 后端本地部署
本阶段只启动平台后端。PostgreSQL 和 Redis 继续只监听服务器回环地址;后端也先监听 `127.0.0.1:3001`,等待统一网关接入。MinIO API 监听经批准的局域网地址,以便后续浏览器和农场工作站使用预签名 URL;MinIO 控制台继续只监听 `127.0.0.1:9001`。
## 前置条件
- 基础设施健康检查已通过。
- 应用数据库初始化和初始化后备份校验已通过。
- 源码位于 `/srv/ai-soulmate/sources/ai-soulmate-server`,分支为 `local-deployment`,且没有未提交的受跟踪文件。
- 局域网地址已经固定或配置 DHCP reservation。地址变化后必须重新生成后端配置并重建相关容器。
## 生成配置
以下示例中的地址是当前 POC 样机地址:
```bash
cd /srv/ai-soulmate-local-deployment
./scripts/configure-backend-env.sh \
compose/.env \
/srv/ai-soulmate/sources/ai-soulmate-server \
192.168.3.102
```
脚本保留已有基础设施密码,补齐后端密钥,文件权限保持为 `600`,并且不会把密钥打印到终端。Tripo Key 默认留空;健康检查不依赖 Tripo,联调 Tripo 前再通过受控方式注入已轮换的新 Key。
## 重建 MinIO 配置
```bash
docker compose --env-file compose/.env \
-f compose/docker-compose.infra.yml \
up -d minio minio-init
./scripts/verify-infra.sh compose/.env
```
该操作不会删除 `ai-soulmate-minio-data` 数据卷。初始化任务会保留 Bucket,并创建无管理权限的应用账号;后端不使用 MinIO 管理员账号。
## 构建并启动后端
```bash
./scripts/build-backend-image.sh \
compose/.env \
/srv/ai-soulmate/sources/ai-soulmate-server
docker compose --env-file compose/.env \
-f compose/docker-compose.backend.yml \
up -d
./scripts/verify-backend.sh compose/.env
```
构建脚本拒绝错误分支、受跟踪源码改动以及与源码提交不一致的镜像标签。后端验证会检查 HTTP 健康状态,以及容器到 PostgreSQL、Redis 和 MinIO Bucket 的实际连接。
## 当前网络边界
| 服务 | 监听地址 | 当前用途 |
| --- | --- | --- |
| PostgreSQL | `127.0.0.1:5432` | 宿主机维护和 Docker 内部访问 |
| Redis | `127.0.0.1:6379` | 宿主机维护和 Docker 内部访问 |
| 后端 | `127.0.0.1:3001` | 本机验收,后续由网关代理 |
| MinIO API | `192.168.3.102:9000` | 局域网预签名上传和下载 |
| MinIO 控制台 | `127.0.0.1:9001` | 仅 SSH 隧道管理 |
不要在路由器上为 `3001`、`5432`、`6379`、`9000` 或 `9001` 配置公网端口转发。正式交付应通过统一网关和 TLS 暴露业务入口,并按客户网络划分限制 MinIO API 来源。
+8 -6
View File
@@ -107,13 +107,15 @@ backup_directory="$(printf '%s\n' "$backup_output" | sed -n 's/^Infrastructure b
## 5. 业务部署门槛
当前 ai-soulmate-server 的 Dockerfile 只有开发目标,开发 Compose 还挂载源码;压缩包中的 ai-soulmate-server-master 没有可验证的 Git 历史。先完成以下改造,再写应用 Compose:
后端本地容器的配置、构建、启动和连接验收见 `docs/BACKEND-DEPLOYMENT.md`。后端先绑定回环地址,数据库和 Redis 不向局域网开放;MinIO API 只绑定批准的局域网地址,控制台保持回环绑定。
1. 平台和管理端引入统一对象存储接口,同时保留 Alibaba OSS provider,并让 MinIO 等本地 S3 provider 通过预签名上传、下载、分片、CORS、权限、元数据和恢复测试。
2. mlkj-admin 增加 AI SoulMate-only profile,不能初始化无关业务库、默认账号或固定密码。
3. 为后端、平台前端和管理端生成生产镜像;禁止源码 bind mount,固定基础镜像版本并记录 digest。
4. 添加迁移、健康检查、资源上限、日志轮换、备份恢复和回滚流程。
5. 再决定是否使用 nginx-server。它只承担环境无关的 TLS、路由、上传限制、访问日志和限流;若现场已有企业网关,优先复用企业网关。
平台后端已有独立镜像、无源码挂载的 Compose、资源上限、日志轮换、健康检查和 MinIO provider。继续完成以下业务门槛:
1. 验证 MinIO 预签名上传、下载、浏览器 CORS、权限和备份恢复。
2. 为平台前端生成生产镜像,并与本地后端完成登录和核心业务联调。
3. 为 mlkj-admin 增加 AI SoulMate-only profile,不能初始化无关业务库、默认账号或固定密码。
4. 固定后端、平台前端和管理端基础镜像版本,记录最终镜像 digest 和回滚版本。
5. 部署环境无关的统一网关,或接入客户已有企业网关,由其承担 TLS、路由、上传限制、访问日志和限流。
## 6. 验收顺序