【AI全栈】my-resume 上线实录：从踩坑到方法论

写在前面#

大半夜还说赢一把，不对，发一版就睡 - - 结果又… 又卡住了。

1
ERROR: failed to build: failed to solve: DeadlineExceeded:
2
failed to fetch oauth token:
3
Post "https://auth.docker.io/token": dial tcp 118.107.180.216:443: i/o timeout

docker pull node:22-slim 明明成功了，buildx 还是超时。 这不是第一次了。

从 my-resume 第一次上线到现在稳定在 v2.3.1， 我遇到的问题大多数不是”代码写错了”， 而是环境、工具链、资源限制这些前端平时碰不到的东西。

这篇想把这个过程完整写下来—— 不只是”怎么发版”，还有”发版稳定之后发现了什么”： 业务验收的漏洞、已知的安全风险、以及我打算怎么走下一步。

还有一件事值得单独说： 这套运维脚本不是我一个人写的，是我和 AI 一起迭代出来的。 哪里麻烦，哪里加——这是整套脚本的生长方式。

一、运维目录是怎么长出来的#

先看现在的目录结构：

1
deploy/
2
├── ecs/
3
│   ├── bootstrap.sh                 # 第一次初始化 ECS 环境
4
│   ├── build-and-push-images.sh     # 本地构建镜像并推送
5
│   ├── release-from-local.sh        # 本地构建 + 推送 + 远程发布，一键（504 行）
6
│   ├── release.sh                   # ECS 侧发布（拉镜像 + snapshot + compose up）
7
│   ├── rollback.sh                  # 出问题回滚到上一个 release snapshot
8
│   ├── deploy-latest-tag.sh         # 快速部署最近一个 tag（日常迭代用）
9
│   ├── sync-base-image.sh           # 同步基础镜像到 ACR（国内加速）
10
│   ├── pre-release-port-cleanup.sh  # 发布前清理端口
11
│   ├── pre-release-disk-cleanup.sh  # 发布前清理磁盘
12
│   ├── render-config.sh             # 渲染模板配置文件
13
│   ├── lib.sh                       # 公共函数库
14
│   └── stack-env-checklist.md       # 环境变量说明文档
15
└── templates/
16
    ├── compose.prod.image.yml.tpl   # image 模式 compose 模板
17
    ├── compose.prod.yml.tpl         # build 模式 compose 模板
18
    ├── nginx.conf.tpl               # nginx 配置模板（HTTPS）
19
    ├── nginx.http.conf.tpl          # nginx 配置模板（HTTP）
20
    └── stack.env.example            # 环境变量示例

这些脚本不是一开始设计好的。

最开始只有一个 release.sh，就是 SSH 上 ECS 跑 docker compose up。 后来发现 ECS 2核2G 跑 next build 会卡死，加了 build-and-push-images.sh。 后来发现每次要分两步执行很麻烦，加了 release-from-local.sh 把两步合一。 后来发现发布前端口经常被占，加了 pre-release-port-cleanup.sh。 后来发现配置文件里有重复逻辑，抽出了 lib.sh。 后来发现构建缓存每次都重新拉依赖，加了 registry cache + 基础镜像私有化。 后来发现出问题回滚要手动切 tag 很慢，加了 rollback.sh + release snapshot 机制。

每一个脚本，都是被一个具体的麻烦逼出来的。

二、lib.sh：公共函数库的设计思路#

lib.sh 是整套脚本的地基，其他脚本都 source 它。 里面解决的是几类重复问题：

1. 统一日志格式

1
log() {
2
  printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$*"
3
}

所有脚本的输出都带时间戳，排障时能看出哪一步卡了多久。

2. dry-run 支持

1
run_cmd() {
2
  if [[ "$DRY_RUN" == '1' ]]; then
3
    log "[dry-run] $*"
4
    return 0
5
  fi
6
  "$@"
7
}

加 --dry-run 参数，只打印命令不执行。 每次改了脚本逻辑，先 dry-run 确认参数对不对，再真正跑。

3. 模板渲染

1
render_template() {
2
  local template_path="$1"
3
  local output_path="$2"
4
  # 用 python3 做变量替换，__VAR_NAME__ 格式
5
  # 缺变量直接报错，不会生成残缺配置
6
}

templates/ 里的 .tpl 文件用 __VAR_NAME__ 占位，渲染时从环境变量里取值。 缺了变量不会静默跳过，直接报错——这个设计救过我几次。

4. 健康检查

1
curl_check() {
2
  local url="$1"
3
  local label="$2"
4
  local max_seconds="${3:-120}"
5
  # 循环重试，超时才报错
6
}

发布完不是立刻验收，而是等服务真正可用再验收。 重试窗口默认 120 秒，2核2G 启动慢，这个时间是跑出来的。

5. 环境变量加载与校验

1
load_stack_env()      # 按优先级查找并加载 stack env 文件
2
require_vars()        # 检查必填变量，缺了直接 die
3
resolve_deploy_mode() # 自动判断 build 模式还是 image 模式

这几个函数加起来，解决了”脚本跑到一半才发现变量没配”的问题。

三、六个真实的坑#

1
ERROR: failed to solve: failed to solve: DeadlineExceeded:
2
failed to fetch oauth token:
3
Post "https://auth.docker.io/token": i/o timeout

1
./deploy/ecs/release-from-local.sh \
2
  --tag v2.3.1 \
3
  --stack-env ./.env.stack.local \
4
  --ecs-host <your-ecs-ip> \
5
  --engine-build

1
# 1. 拉官方镜像
2
docker pull node:22-slim
3

4
# 2. 打 tag 推到自己的 ACR
5
BASE_REPO=crpi-xxxxxx.cn-chengdu.personal.cr.aliyuncs.com/fridolph-space/my-resume-base-node
6
docker tag node:22-slim $BASE_REPO:22-slim
7
docker tag node:22-slim $BASE_REPO:22-slim-20260421  # 带日期的不可变备份
8
docker push $BASE_REPO:22-slim
9
docker push $BASE_REPO:22-slim-20260421
10

11
# 3. 验证
12
docker manifest inspect $BASE_REPO:22-slim >/dev/null && echo "ACR base image OK"

1
DEPLOY_BASE_IMAGE=crpi-xxxxxx.cn-chengdu.personal.cr.aliyuncs.com/fridolph-space/my-resume-base-node:22-slim

1
docker manifest inspect $SERVER_IMAGE:$TAG >/dev/null || die "server manifest missing"
2
docker manifest inspect $WEB_IMAGE:$TAG >/dev/null    || die "web manifest missing"
3
docker manifest inspect $ADMIN_IMAGE:$TAG >/dev/null  || die "admin manifest missing"

1
server:
2
  healthcheck:
3
    test: ["CMD", "curl", "-f", "http://localhost:5577/api"]
4
    interval: 10s
5
    timeout: 5s
6
    retries: 12       # 最多等 120 秒
7
    start_period: 30s # 启动缓冲期

1
Mixed Content: The page at 'https://resume.fridolph.top' was loaded over HTTPS,
2
but requested an insecure resource 'http://server:5577/api/...'

1
NEXT_PUBLIC_API_BASE_URL=https://api-resume.fridolph.top  # 浏览器用，构建时注入
2
RESUME_API_BASE_URL=http://server:5577                    # 服务端 SSR 用，运行时注入

1
GET /api/auth/me          → 200  ✅
2
GET /api/resume/published → 500: no such table: resume_publication_snapshots

1
# 第一步：表结构存不存在
2
python3 - <<'PY'
3
import sqlite3
4
conn = sqlite3.connect('/root/my-resume/.deploy-runtime/shared/data/my-resume.db')
5
tables = [r[0] for r in conn.execute("select name from sqlite_master where type='table'")]
6
print("resume_publication_snapshots:", "resume_publication_snapshots" in tables)
7
PY
8

9
# 第二步：业务数据存不存在
10
# 接口返回 200 不等于业务可用，要看到数据才算
11
curl -s https://api-resume.fridolph.top/api/resume/published | python3 -m json.tool

四、AI 辅助写脚本：我的工作方式#

release-from-local.sh 现在有 500 多行，支持十几个参数。

但它最开始只是一条命令：

1
ssh root@<ecs-ip> "cd /opt/my-resume && ./deploy/ecs/release.sh v2.1.0"

是怎么长成现在这样的？不是一次设计好的，是一次次被问题推着加的。

我的工作方式：

1
1. 遇到麻烦，描述给 AI
2
     ↓
3
2. AI 给初版方案或修改建议
4
     ↓
5
3. 跑一遍，把报错贴给 AI
6
     ↓
7
4. AI 解释根因 + 给修改
8
     ↓
9
5. 验证通过，沉淀进脚本或文档

比如 --engine-build，是因为 buildx 超时加的。 比如 --reuse-from-tag，是因为只改了 server 但不想重新构建 web/admin 加的。 比如 --cache-ref，是因为构建缓存每次都重新拉依赖，加了 registry cache 引用。 比如 --skip-public-check，是因为有时候只想验证 ECS 侧，不想等公网检查加的。 比如 rollback.sh，是因为手动切 tag + 重启太慢，需要自动回滚。

每一个参数背后，都有一个具体的麻烦。

AI 在这个过程里做什么？

• 生成初版脚本框架
• 解释报错的根因（buildx 不共享宿主机缓存这件事，我自己不一定能想到）
• 提供备选方案（--engine-build 还是私有化基础镜像，两个方案都是 AI 给的）
• 帮我把”我的需求”翻译成”bash 的正确写法”

我做什么？

• 提需求，描述麻烦
• 验证，看日志，判断对不对
• 决定用哪个方案
• 把结果沉淀进文档

脚本是 AI 写的，但判断是我做的。

五、2核2G ECS 的运维原则#

跑了这么多版本，总结下来就这几条：

构建不上 ECS。 本地或 CI 构建镜像，ECS 只拉取启动。 2核2G 跑 next build 会把内存打满，直接卡死。

串行不并发。 拉三个镜像串行，不并发。磁盘 40G，并发拉容易满。

release snapshot 管理。 ECS 保留最近两个版本的 snapshot 目录（release-snapshots/v2.3.0、v2.3.1）， 通过 current 软链接指向当前运行版本。 旧镜像 docker image prune -f 定期清理。

tag 有纪律。 用 v2.3.1，不用 latest。 出了问题，rollback.sh 一键切回上一个 snapshot。

发布前体检。 端口可用、磁盘可用、manifest 齐全，三连通过才发布。 这三个检查加起来不到 10 秒，但能拦住大多数”发到一半失败”的情况。

六、已知的安全风险（诚实说）#

部署稳定之后，我做了一轮联调，发现了另一类问题—— 不是”发不出去”，而是”发出去了但不安全”。

目前这套上线的东西，安全层面是在持续完善的。 作为学习项目公开出来，有必要把风险和进展都写清楚。

七、沉淀成什么#

现在每次发版的完整流程：

1
# 1. 保持代码和 tag 最新
2
git checkout main && git pull origin main && git fetch --tags --force
3

4
# 2. 一键构建 + 推送 + 远程发布
5
./deploy/ecs/release-from-local.sh \
6
  --tag v2.3.1 \
7
  --stack-env ./.env.stack.local \
8
  --ecs-host <your-ecs-ip>
9

10
# 脚本自动完成：
11
#   - 检查 git tag，不存在自动创建并推送
12
#   - 三服务 manifest 验证
13
#   - 本地构建镜像（用 ACR 基础镜像，不依赖 DockerHub）
14
#   - 推送到 GHCR
15
#   - SSH 到 ECS 执行 release.sh
16
#   - ECS 创建 release snapshot、切换 current 软链接
17
#   - compose up + 健康检查三个公网域名

只改后端时，只构建 server（web/admin 从上一个 tag 复用）：

1
./deploy/ecs/release-from-local.sh \
2
  --tag v2.3.1 \
3
  --stack-env ./.env.stack.local \
4
  --ecs-host <your-ecs-ip> \
5
  --services server

快速部署最近一个已有 tag：

1
./deploy/ecs/deploy-latest-tag.sh --ecs-host <your-ecs-ip>

出了问题，回滚：

1
./deploy/ecs/rollback.sh   # 自动切到上一个 release snapshot

八、现在在哪里，下一步去哪里#

诚实地说，现在的状态是：

1
✅ L1 基础可用
2
    镜像化发布、ECS pull + up、健康检查、回滚
3

4
✅ L2 联调稳定
5
    DB 同步、API 基址一致性、环境变量分层
6
    release snapshot 管理 + rollback
7

8
✅ L2.5 安全加固（持续进行中）
9
    ✅ API 响应契约标准化 + Swagger 注解
10
    ✅ JWT 鉴权 + 角色能力守卫
11
    ✅ AI 调用记录 + Chat 治理台
12
    ✅ 输入治理（简历导入识别中的安全过滤）
13
    🔄 全量 zod schema 校验（部分已做）
14

15
✅ L3 研发效率
16
    ✅ 构建缓存优化（registry cache + 基础镜像私有化）
17
    ✅ 增量发布（--services 按需构建 + --reuse-from-tag）
18
    ✅ release snapshot 软链接管理
19

20
⬜ L4 生产可靠性
21
    蓝绿发布、自动回滚、告警体系
22

23
⬜ L5 企业治理
24
    镜像安全扫描、多环境权限分级（暂不考虑）

L4 以上，我现在没有足够的实际经历，不打算在这里展开。 等真正做了，再写。

接下来的优先级： 把部署这件事放下，去做 AI 实战。 安全加固会随着功能开发一起补，不单独开一个阶段做。

写在最后#

三篇写下来，我想说两件事。

第一件：这套东西现在是学习项目，不是生产系统。

API 校验还没全量覆盖，安全加固还在持续做—— 这些我都知道，也都写出来了。 不是因为不重要，是因为我现在的阶段， 比起”做完整”，更重要的是”做清楚”： 清楚自己在哪里，清楚风险在哪里，清楚下一步去哪里。

第二件：工具可以借，经验得自己攒。

这套脚本是 AI 帮我写的，但每一行背后的判断是我做的。 每一个坑，是我踩的。每一个 SOP，是我验证过的。

如果你也在学全栈，希望这篇能让你少踩几个坑。 如果你发现了我写错的地方，欢迎告诉我—— 我们一起学，一起改。

参考#

• Docker buildx 文档
• 阿里云容器镜像服务 ACR
• GitHub Container Registry (GHCR)
• Compose healthcheck
• Twelve-Factor App

昇哥 · 2026年5月（2026年6月更新） my-resume 从 v1.1.0 跑到 v2.3.1 途中，把踩过的坑写下来