生产环境部署实战记录 (2025-12-21)

本页面记录了一刻工坊在阿里云 Ubuntu 环境下的完整部署复盘，包含遇到的坑及最终解决方案，为后续二次部署提供参考。

概览

• 服务器: 阿里云 ECS (Ubuntu 22.04)
• 域名: *.landi.asia
• 架构: Nginx 反向代理 + Node.js (PM2) + Python (Systemd) + PostgreSQL

坑位与排雷指南

1. Node.js 版本陷阱

现象: ReferenceError: File is not defined原因: 后端使用了某些依赖（如 undici），需要 Node 20+ 的全局 File 对象支持。 对策:

# 升级 Node 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

2. 数据库迁移顺序

现象: relation "Projects" does not exist原因: 迁移文件的时间戳决定了执行顺序。如果关联表（如 Batches）的时间戳早于被关联表（如 Projects），迁移会失败。 对策: 手动修正迁移文件名前缀的时间戳，确保依赖表先于关联表创建。

3. Nginx 域名冲突

现象: 访问 A 域名跳到了 B 域名。 原因: 多个 server_name 配置中包含了重复或重叠的域名。 对策:

• 每个子域名独立一个 .conf 文件。
• 根域名 landi.asia 与子域名 docs.landi.asia 必须在配置中严格区分。

4. SSL 证书扩展

现象: 新加子域名后，原来的 HTTPS 报错。 对策:

# 扩展现有证书
sudo certbot --nginx -d api.landi.asia -d agent.landi.asia -d docs.landi.asia -d studio.landi.asia -d admin.landi.asia
# 选 (E)xpand

部署 SOP (精简版)

1. 环境检查: 运行 01-env-check.sh，确保 Node 20, Python 3.10+, PostgreSQL 16。
2. 数据库预设:
   • 手动创建数据库 kkmusic_production。
   • 手动安装 pgvector 扩展。
3. 后端部署:
   • npm install --production
   • npm run db:migrate
   • pm2 start ecosystem.config.js
4. AI Agent 部署:
   • 创建 venv 环境。
   • 安装依赖并启动 Systemd 服务。
5. 前端部署:
   • 打包 frontend-dist.zip。
   • 手动解压至 /var/www/kkmusic-frontend。
   • 配置 Nginx 并重载。
6. 全站 HTTPS: 运行 certbot 扩展所有子域名。

最终运行状态

• API: https://api.landi.asia
• Agent: https://agent.landi.asia
• Studio: https://studio.landi.asia
• Admin: https://admin.landi.asia
• Docs: https://docs.landi.asia

---

最后更新: 2025-12-21