Loom 生产部署手册

目标：把 Loom 全栈部署到 ai.aidfxn.com，使用 Docker Compose + Let's Encrypt 自动证书。

0. 前置条件（部署前必须就绪）

项	要求
服务器	Linux（Ubuntu 22.04+ / Debian 12+ / CentOS 9+ 均可），2 vCPU / 4 GB RAM / 30 GB 磁盘起步
软件	`docker` 24+、`docker compose v2`、`openssl`、`curl`、`python3`
防火墙	开放 80 / 443 到公网（80 是 Let's Encrypt 挑战用）
域名	`ai.aidfxn.com` 的 A 记录指向服务器公网 IP（TTL ≤ 10 min 便于调试）
邮箱	Let's Encrypt 续签通知邮箱（`deploy.sh` 里默认 `runzi.lao@gmail.com`，可改）

校验 DNS 是否生效：

dig +short ai.aidfxn.com
# 应返回你的服务器公网 IP

1. 首次部署步骤

1.1 把项目推到服务器

推荐方式：git 仓库；临时方案：rsync -avz --exclude='.venv' --exclude='node_modules' --exclude='*.pyc' loom/ user@SERVER:/opt/loom/

ssh user@SERVER
cd /opt/loom

1.2 生成生产 .env

cp .env.production.example .env

# 生成 3 个密钥并手动填进 .env
openssl rand -hex 32                                          # → APP_SECRET_KEY
openssl rand -base64 24                                       # → POSTGRES_PASSWORD
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"  # → FERNET_KEY

vi .env     # 填入上面 3 个值；其余 LOBSTER_*、OPENAI_* 可先留空（可在 UI 里补）

重要：FERNET_KEY 生成后严禁再改 —— 所有已加密字段（平台账号密码、LLM API Key、龙虾 API Key 等）都依赖它解密。

1.3 一键部署

bash scripts/deploy.sh

该脚本会：

校验 .env 必填项 + 替换 DATABASE_URL 中的占位符
构建前后端镜像
首次运行时通过 Let's Encrypt 申请 TLS 证书（HTTP-01 挑战）
起全栈（postgres / redis / backend / frontend / certbot）
轮询 /api/v1/healthz 直到后端就绪

成功后访问 https://ai.aidfxn.com/，使用 admin / admin123 登录（首次登录立刻修改密码）。

2. 验证清单

检查	方法	通过标志
HTTPS 生效	`curl -I https://ai.aidfxn.com/`	`HTTP/2 200` + `strict-transport-security` 头
HTTP → HTTPS 重定向	`curl -I http://ai.aidfxn.com/`	`HTTP/1.1 301`，`Location: https://...`
健康检查	`curl https://ai.aidfxn.com/api/v1/healthz`	`{"code":0,"data":{"db":"ok","redis":"ok",...}}`
登录可用	浏览器进入首页登录	`admin` / `admin123` 能进仪表盘
证书自动续签	`docker compose logs certbot`	12 小时循环 `certbot renew` 输出
容器 `restart: always`	`docker compose ps`	`STATUS` 均为 `Up`

3. 日常运维

# 查容器
docker compose -f docker-compose.yml -f docker-compose.prod.yml ps

# 查日志（后端滚动 / nginx 访问）
docker compose -f docker-compose.yml -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.yml -f docker-compose.prod.yml logs -f frontend

# 进 backend 跑 alembic / 种子 / pytest
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend alembic upgrade head
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend python -m app.scripts.seed

# 备份数据库
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec -T postgres \
  pg_dump -U loom loom > backup-$(date +%Y%m%d).sql

# 恢复
cat backup-YYYYMMDD.sql | docker compose -f docker-compose.yml -f docker-compose.prod.yml exec -T postgres \
  psql -U loom loom

4. 升级流程（零停机不保证，约 30-60s 抖动）

cd /opt/loom
git pull                                                                  # 或 rsync 覆盖
docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile full build backend frontend
docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile full up -d

# 数据库迁移（镜像 entrypoint 会自动跑，但建议显式跑一次查结果）
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend alembic upgrade head

如果迁移风险高，先在步骤 2 之前 pg_dump 备份。

5. 回滚

# 代码回滚
git reset --hard <上一个已知 good commit>
docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile full up -d --build

# 迁移回滚（仅支持可逆迁移）
docker compose -f docker-compose.yml -f docker-compose.prod.yml exec backend alembic downgrade -1

不可逆迁移需从 pg_dump 备份恢复。

6. 常见问题

现象	排查
`deploy.sh` 卡在证书申请	检查 `dig ai.aidfxn.com` 是否指向本机；服务器 80 端口是否被其它服务占用（`sudo lsof -i :80`）
首页 502	`docker compose logs frontend` + `docker compose logs backend`，多半是 backend 还没就绪或 `.env` 缺字段
登录 `admin/admin123` 401	数据库里还没有 seed；进 backend 容器跑 `python -m app.scripts.seed`
任务执行报 LLM 401	先看「系统设置 → 执行器配置 → 龙虾 Agent」有没有配 `api_key`；或 `.env` 的 `OPENAI_API_KEY` / `LOBSTER_API_KEY` 是否真实有效
证书到期	`certbot` 容器每 12h 自动续签；手动续签：`docker compose -f ... exec certbot certbot renew`

7. 敏感信息清单（切勿提交到代码仓库）

.env（生产凭据）
certbot/conf/ 整个目录（Let's Encrypt 私钥 + 账号凭据）
数据库备份 backup-*.sql（含加密后的业务凭据）

建议服务器侧 chmod 600 .env + chown root:root 严格权限。

5.6 KiB Raw Permalink Blame History Unescape Escape