本文以我的 AI 求职助手简喵为例，完整记录一个 AI 应用从本地打包、上传服务器、Docker Compose 启动、绑定域名、配置 Cloudflare、验证 AI / PDF / 登录链路，到上线后排错和备份的全过程。

简喵在线体验地址：在线体验
GitHub README: RyanCoreAI/AIResume
AI应用生产级护栏：限流、日志、降级、缓存、审计、成本

当前核心链路是：

简历模板 / 编辑
→ 目标岗位分析
→ 岗位竞争力诊断
→ 投递文案
→ PDF 导出

完整AI核心链路验证请看上一篇文章：blog

项目技术栈：

前端：Vue 3 + Vite + Nginx
后端：Spring Boot + MySQL + Redis
AI：DeepSeek / 智谱等模型 API
PDF：Puppeteer 独立服务
部署：阿里云 ECS + Docker Compose + Cloudflare

部署架构图如下：

选择这个架构的原因：

1. 所有服务都在一台 ECS 上，部署和排错简单。
2. MySQL、Redis、Puppeteer 不暴露公网。
3. 只有 Nginx 的 80 / 443 对外。
4. Cloudflare 做 DNS、HTTPS、基础防护和访问分析。
5. Docker volume 保存数据库、头像上传、PDF 导出文件。

二、服务器选择与安全组

服务器配置当前项目是2核4G：

阿里云 ECS
Ubuntu / Debian 系 Linux
2C4G 
公网开放 80 / 443
SSH 只允许自己的固定 IP
MySQL / Redis / backend / puppeteer 一律不开放公网

具体流程如下：

阿里云控制台
→ 云服务器 ECS
→ 创建实例
→ 选择 Ubuntu / Debian
→ 规格选择 2C4G
→ 安全组只开放 80 / 443 / 自己 IP 的 22
→ 创建后记录公网 IP
→ 通过远程连接或本地 SSH 登录

本项目使用2核4G云服务器，购买后启动云服务器并点击远程连接服务器设置密码并登录服务器。

阿里云安全组建议：

允许：
80/tcp   0.0.0.0/0
443/tcp  0.0.0.0/0
22/tcp   你的固定公网 IP/32

禁止公网开放：
3306 MySQL
6379 Redis
8080 backend
3001 Puppeteer

阿里云官方也建议，公网 Web 服务只开放 80 / 443；SSH 只允许指定管理 IP；数据库端口不要直接暴露公网。

登录成功后会显示如下：

三、本地发布前检查

在本地项目根目录执行：

cd D:\AIResume
git status --short
git diff --check

确认工作区没有临时文件、调试文件、密钥文件。

前端检查：

npm --prefix frontend install
npm --prefix frontend run build
npm --prefix frontend audit --omit=dev --audit-level=high

后端检查：

mvn -f backend/pom.xml "-Dspring.profiles.active=test" test

如果只想先跑核心链路测试：

mvn -f backend/pom.xml "-Dspring.profiles.active=test" "-Dtest=*Score*,*JobOptimization*,*Pdf*,*DeliveryNote*,*Share*" test

Puppeteer PDF 服务检查：

npm --prefix puppeteer-service install
npm --prefix puppeteer-service audit --omit=dev --audit-level=high
node -c puppeteer-service/index.js

Compose 配置检查：

docker compose config --quiet

这一关过不去，不要上服务器。

四、项目 Docker 打包方式

简喵采用多阶段构建。

后端 backend/Dockerfile 思路：

第一阶段：JDK + Maven 编译 Spring Boot jar
第二阶段：JRE 运行 jar
最终镜像只带运行时，不带完整构建环境

Docker 官方推荐多阶段构建，因为可以把构建依赖留在前一阶段，只把最终产物复制到运行镜像里，减少镜像体积和攻击面。

前端 frontend/Dockerfile 思路：

第一阶段：Node 20 执行 npm ci + npm run build
第二阶段：Nginx 托管 dist 静态文件

Puppeteer 服务：

Node 20 + Chromium + 中文字体
只暴露容器内 3001，不映射到公网

我没有把 Puppeteer 直接塞进 Spring Boot 容器里，而是拆成独立服务。原因是 Chromium 依赖重、字体依赖多、启动和排错都更复杂。拆成独立容器后，后端只需要调用 PDF 服务，PDF 出问题时也能单独看 puppeteer 日志，不会把后端容器搞得很臃肿。

本地可以先构建一次：

cd D:\AIResume
docker compose build backend frontend puppeteer

五、上传代码到服务器

推荐两种方式。

方式 A：服务器直接拉私有仓库

服务器上执行：

cd /opt
git clone <你的私有仓库地址> AIResume
cd /opt/AIResume

后续更新：

cd /opt/AIResume
git pull

方式 B：本地打包上传

本地 PowerShell：

cd D:\AIResume
git archive --format=tar --output jianmiao-src.tar HEAD
scp -i $env:USERPROFILE\.ssh\jianmiao_codex_ed25519 .\jianmiao-src.tar root@<ECS_PUBLIC_IP>:/opt/

服务器：

mkdir -p /opt/AIResume
tar -xf /opt/jianmiao-src.tar -C /opt/AIResume
cd /opt/AIResume

注意：不要把 .env、数据库文件、日志、导出的 PDF、真实上传头像一起打包。

六、服务器安装 Docker

Ubuntu / Debian 示例：

apt update
apt install -y ca-certificates curl gnupg git openssl apache2-utils

安装 Docker 官方源：

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

添加源后安装：

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

验证：

docker version
docker compose version

七、创建生产环境变量

不要将AI API Key在代码中硬编码暴露极易造成泄露导致AI额度刷爆，敏感配置统一用.env注入。

进入项目目录：

cd /opt/AIResume
cp .env.example .env
chmod 600 .env
nano .env

关键变量不要写进文章、截图、GitHub、聊天记录。

生产必须填：

MYSQL_ROOT_PASSWORD=换成强密码
MYSQL_PASSWORD=换成强密码
REDIS_PASSWORD=换成强密码

JWT_SECRET=至少32字符以上强随机
ADMIN_AUDIT_ENCRYPTION_KEY=至少32字符以上强随机
BACKUP_ENCRYPTION_PASSPHRASE=备份加密口令

DEEPSEEK_API_KEY=你的模型服务 key
ZHIPU_API_KEY=你的模型服务 key

APP_BASE_URL=https://jianmiao.yanxai.com
PDF_PREVIEW_BASE_URL=http://frontend
APP_ALLOWED_HOSTS=jianmiao.yanxai.com,frontend,localhost,127.0.0.1

COOKIE_SECURE=true
REGISTRATION_ENABLED=true

生成随机值可以用：

openssl rand -base64 48

再次强调：

.env 只存在服务器本地
不要提交 Git
不要发到聊天工具
不要截图
不要传到 GitHub
否则你的AI API额度会被滥用或刷爆

八、配置 Nginx 管理后台密码

如果项目里有 admin 路径，建议前面再加一层 Basic Auth。

cd /opt/AIResume
mkdir -p deploy/nginx
htpasswd -c deploy/nginx/admin.htpasswd admin
chmod 600 deploy/nginx/admin.htpasswd

执行后会让你输入密码。不要把密码写到命令行里。

九、配置 HTTPS 证书

两种选择。

方式 A：Cloudflare Origin Certificate

在 Cloudflare 后台生成 Origin Certificate，然后放到：

/opt/AIResume/deploy/certs/fullchain.pem
/opt/AIResume/deploy/certs/privkey.pem

权限：

chmod 600 deploy/certs/privkey.pem

Cloudflare SSL 模式选择：

Full strict

Cloudflare 官方说明，Full strict 会要求源站证书有效、未过期，并且证书域名匹配。不要用 Flexible SSL，否则容易出现登录、跳转、Cookie 和回调问题。

方式 B：Let’s Encrypt

如果你不用 Cloudflare Origin Cert，也可以用 Certbot 申请公开证书。

但如果站点已经走 Cloudflare，首版用 Origin Certificate 更简单。

十、第一次启动服务

先检查 Compose：

cd /opt/AIResume
docker compose config --quiet

启动基础服务：

docker compose up -d mysql redis puppeteer
docker compose ps

确认 MySQL / Redis healthy 后启动后端：

docker compose up -d backend
docker compose logs backend --tail=200

后端第一次启动会执行 Flyway 数据库迁移。

如果后端 healthy，再启动前端：

docker compose up -d frontend
docker compose ps

完整启动也可以直接：

docker compose up -d --build

查看状态：

docker compose ps

正常应该看到：

airesume-mysql       healthy
airesume-redis       healthy
airesume-backend     healthy
airesume-puppeteer   healthy
airesume-frontend    healthy

十一、Cloudflare 绑定域名

Cloudflare DNS 添加：

Type: A
Name: jianmiao
Content: <ECS_PUBLIC_IP>
Proxy status: 先 DNS only，验证成功后再 Proxied
TTL: Auto

Cloudflare 官方说明，Proxied 模式会让 HTTP/HTTPS 流量经过 Cloudflare；DNS only 会直接暴露源站 IP。

添加子域名并绑定服务器域名同时开启代理云

等待代理云配置成功后访问：

点击访问域名

域名绑定成功

建议顺序：

1. DNS 可以先 DNS only 验证 HTTP 或容器服务是否通。
2. 配好 Origin Certificate 后，不要长期让用户 DNS only 直连 HTTPS。
3. 开启 Proxied。
4. SSL/TLS 选择 Full strict。
5. 用浏览器访问 Cloudflare 代理后的域名验证。

不要一开始就全部打开，否则排错困难。

十二、上线后基础验证

服务器本地验证：

curl -I http://127.0.0.1/
curl -kI https://127.0.0.1/

公网验证：

curl -I https://jianmiao.yanxai.com/
curl -fsSL https://jianmiao.yanxai.com/robots.txt
curl -fsSL https://jianmiao.yanxai.com/sitemap.xml

看日志：

docker compose logs frontend --tail=100
docker compose logs backend --tail=200
docker compose logs puppeteer --tail=100

十三、AI 应用必须做的 smoke test

上线不是首页能打开就算成功。AI 应用至少要完整跑一遍主链路：

1. 注册 / 登录
2. 创建简历
3. 保存版本
4. 粘贴真实 JD
5. 跑目标岗位分析
6. 跑岗位竞争力诊断
7. 生成投递文案
8. 导出 PDF
9. 打开 PDF，确认第一页非空、样式和预览一致
10. 创建分享链接

具体验证可以看我上一篇文章跑了一次完整的AI核心链路：
blog

对应要记录：

resumeId
versionId
jobSessionId
scoreId
pdf taskId
AI provider
PDF 文件大小
失败日志

十四、GitHub 登录怎么配置

GitHub 后台路径：

GitHub
→ Settings
→ Developer settings
→ OAuth Apps
→ New OAuth App

填写：

Application name:
简喵 JianMiao

Homepage URL:
https://jianmiao.yanxai.com

Authorization callback URL:
https://jianmiao.yanxai.com/api/v1/auth/github/callback

GitHub 官方文档说明，OAuth App 需要填写 Homepage URL 和 Authorization callback URL，而且 OAuth App 只能有一个 callback URL。

拿到 Client ID / Client Secret 后，只写到服务器 .env：

GITHUB_CLIENT_ID=你的 Client ID
GITHUB_CLIENT_SECRET=你的 Client Secret
GITHUB_REDIRECT_URI=https://jianmiao.yanxai.com/api/v1/auth/github/callback

重启后端：

docker compose up -d backend
docker compose logs backend --tail=100

GitHub 登录不消耗你的 AI API。它只走 GitHub OAuth 授权，不调用 DeepSeek / 智谱。

验证GitHub登录如下：

十五、PDF 导出要重点排查

PDF 是简喵的核心链路，最容易出问题。

检查 Puppeteer：

docker compose logs puppeteer --tail=200

检查后端 PDF 任务：

docker compose logs backend --tail=300 | grep -i pdf

常见问题：

1. APP_BASE_URL 配错
2. PDF_PREVIEW_BASE_URL 配错
3. Puppeteer 访问不到 frontend 容器
4. preview token 失效
5. 字体缺失，中文变乱码
6. 富文本样式被 sanitizer 或导出 CSS 丢掉
7. 简历预览两页，但 PDF 被压成一页

简喵的原则是：

编辑器预览是什么样
导出前预览就是什么样
最终 PDF 就应该是什么样

如果三者不一致，优先查 preview route、导出 CSS、分页容器和 Puppeteer 日志。

用WPS Office打开导出的PDF简历进行预览如下：

所有样式均与预览一致

十六、AI 服务要做限流

AI 应用上线后，最怕两件事：

1. 被刷接口，费用爆炸
2. 模型超时，用户一直等

建议配置：

AI_TASK_WORKER_COUNT=1
AI_TASK_GLOBAL_ACTIVE_LIMIT=6
ASYNC_TASK_QUEUE_LIMIT=50

PDF_TASK_QUEUE_LIMIT=10
PDF_TASK_USER_DAILY_LIMIT=20
PDF_TASK_IP_DAILY_LIMIT=50

小机器先保守一点，不要一上来开太高并发。

十七、上传文件和头像怎么处理

首版可以用本机 Docker volume：

uploads_data: 用户头像、上传文件
exports_data: PDF 导出文件

头像上传必须做：

限制大小
校验 Content-Type
校验 magic bytes
拒绝 SVG / HTML 伪装
重新编码成 JPG
随机文件名

如果以后用户变多，再迁移 OSS：

阿里云 OSS 私有 bucket
后端代理上传
RAM 最小权限
前端不暴露 AK/SK
CSP 和 Puppeteer 白名单加入 OSS 域名

首版不要同时引入腾讯云 COS、阿里云 OSS、Cloudflare R2，复杂度会爆。

十八、备份

数据库备份：

cd /opt/AIResume
set -a
. ./.env
set +a

mkdir -p backups/mysql

docker compose exec -T mysql sh -lc \
'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysqldump -uroot --single-transaction airesume' \
| gzip \
| openssl enc -aes-256-cbc -salt -pbkdf2 \
  -pass env:BACKUP_ENCRYPTION_PASSPHRASE \
  -out backups/mysql/airesume-$(date +%F).sql.gz.enc

上传目录备份：

mkdir -p backups/uploads

docker run --rm \
  -v airesume_uploads_data:/data:ro \
  -v $(pwd)/backups/uploads:/backup \
  alpine sh -lc \
  'tar -czf /backup/uploads-$(date +%F).tar.gz -C /data .'

备份不是做完就算，必须至少恢复演练一次。

十九、常见故障排查

1. docker compose ps 提示 no configuration file

说明你不在项目目录。

cd /opt/AIResume
docker compose ps

2. 前端 502

通常是 backend 不健康。

docker compose ps
docker compose logs backend --tail=200

3. 后端连不上 MySQL

检查：

docker compose ps mysql
docker compose logs mysql --tail=100
docker compose logs backend --tail=200

常见原因：

MySQL 没 healthy
.env 密码不一致
数据库 volume 初始化异常
Flyway 迁移失败

4. GitHub 登录失败

检查：

GitHub OAuth callback URL 是否完全一致
.env 的 GITHUB_CLIENT_ID / SECRET 是否填了
GITHUB_REDIRECT_URI 是否是 https://jianmiao.yanxai.com/api/v1/auth/github/callback
Cloudflare 是否没有拦 callback
后端日志是否有 40301 / OAuth error

5. PDF 导出失败

检查：

docker compose logs backend --tail=300 | grep -i pdf
docker compose logs puppeteer --tail=300

重点看：

taskId
preview URL
Puppeteer allowed host
页面 ready 超时
PDF 文件是否生成
PDF 文件大小是否为 0

二十、回滚

如果刚部署的新版本有问题：

cd /opt/AIResume
git log --oneline -5
git checkout <上一个可用 commit>
docker compose up -d --build backend frontend puppeteer
docker compose ps

原则：

代码可以回滚
数据库迁移不要随便回滚
Flyway 已执行的迁移要优先前向修复

所以数据库变更必须非常谨慎。

二十一、上线 checklist

上线前至少确认：

[ ] ECS 安全组只开放 80 / 443 / 固定 IP 的 SSH
[ ] MySQL / Redis / backend / Puppeteer 不暴露公网
[ ] .env 只在服务器本地，权限 600
[ ] Cloudflare SSL 是 Full strict
[ ] docker compose config --quiet 通过
[ ] 所有容器 healthy
[ ] 注册 / 登录正常
[ ] GitHub 登录正常
[ ] 简历保存正常
[ ] JD 诊断正常
[ ] 岗位竞争力诊断正常
[ ] 投递文案正常
[ ] PDF 导出正常
[ ] 分享链接正常
[ ] robots.txt / sitemap.xml 正常
[ ] 数据库和上传目录有加密备份

结语

AI 应用工程化的关键，不是把 Demo 包装成产品，而是让系统在真实环境里可用、可查、可恢复、可保护，并且能持续迭代。真正麻烦的是：

AI key 不能泄露
用户数据不能乱传
PDF 不能失败
模型超时要兜底
移动端要能用
数据库要能恢复
服务器不能裸奔

简喵这类项目最适合的首版部署方式不是复杂的 K8s，而是：

ECS + Docker Compose + Cloudflare + 严格安全组 + 明确备份 + 完整 smoke test

先把一条真实用户链路跑稳，再考虑扩容、对象存储、CDN、队列和更多自动化运维。

参考官方文档：

• Docker Compose 生产部署文档
• Docker 多阶段构建文档
• Cloudflare Full strict SSL 文档
• Cloudflare DNS Proxy 文档
• 阿里云 ECS 安全组实践
• GitHub OAuth App 文档

以上就是我这次把简喵从本地部署到公网可访问的完整记录。后面我会继续补充限流、日志、降级、缓存、审计和成本控制这些 AI 应用上线后的工程细节。
我是Ryan，我的技术博客，关注可信 AI 应用工程。简喵是我把这个方向落到真实产品里的一个项目：不只追求 AI 生成结果看起来漂亮，更关注它有没有证据、能不能追溯、上线后能不能稳定运行。