「部署复盘」二、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.2.13， 我遇到的问题大多数不是”代码写错了”， 而是环境、工具链、资源限制这些前端平时碰不到的东西。

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

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

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

先看现在的目录结构：

1
deploy/
2
├── ecs/
3
│   ├── bootstrap.sh                 # 第一次初始化 ECS 环境
4
│   ├── build-and-push-images.sh     # 本地构建镜像并推送
5
│   ├── release-from-local.sh        # 本地构建 + 推送 + 远程发布，一键
6
│   ├── release.sh                   # ECS 侧发布（只拉镜像启动）
7
│   ├── rollback.sh                  # 出问题回滚到上一个 tag
8
│   ├── pre-release-port-cleanup.sh  # 发布前清理端口和磁盘
9
│   ├── render-config.sh             # 渲染模板配置文件
10
│   ├── lib.sh                       # 公共函数库
11
│   └── stack-env-checklist.md       # 环境变量说明文档
12
└── templates/
13
    ├── compose.prod.image.yml.tpl   # image 模式 compose 模板
14
    ├── compose.prod.yml.tpl         # build 模式 compose 模板
15
    ├── nginx.conf.tpl               # nginx 配置模板（HTTPS）
16
    ├── nginx.http.conf.tpl          # nginx 配置模板（HTTP）
17
    └── 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。

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

二、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: 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
  --version 2.2.13 \
3
  --stack-env ./.env.stack.local \
4
  --ecs-host 8.137.34.240 \
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 现在有 300 多行，支持十几个参数。

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

1
ssh root@8.137.34.240 "cd /opt/my-resume && ./deploy/ecs/release.sh v2.2.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 加的。 比如 --skip-public-check，是因为有时候只想验证 ECS 侧，不想等公网检查加的。

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

AI 在这个过程里做什么？

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

我做什么？

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

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

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

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

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

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

只保留最近一个版本。 历史镜像只留一个，够回滚就行。docker image prune -f 定期跑。

tag 有纪律。 用 v2.2.13，不用 latest。 出了问题，回滚就是改 tag 重启，不需要重新排查。

发布前体检。 端口可用、磁盘可用、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
  --version 2.2.13 \
7
  --stack-env ./.env.stack.local \
8
  --ecs-host 8.137.34.240 \
9
  --ecs-user root \
10
  --ecs-port 22
11

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

只改后端时，只构建 server：

1
./deploy/ecs/release-from-local.sh \
2
  --version 2.2.13 \
3
  --stack-env ./.env.stack.local \
4
  --ecs-host 8.137.34.240 \
5
  --services server

出了问题，回滚：

1
./deploy/ecs/rollback.sh --tag v2.2.12 --ecs-host 8.137.34.240

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

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

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

4
✅ L2 联调稳定
5
    DB 同步、API 基址一致性、环境变量分层
6

7
🔄 L2.5 安全加固（进行中，还不完整）
8
    输入校验、限流、AI 用量控制
9

10
⬜ L3 研发效率（还没开始）
11
    按变更范围构建、构建缓存优化
12

13
⬜ L4 生产可靠性（还没开始）
14
    蓝绿发布、自动回滚、告警体系
15

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

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

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

写在最后#

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

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

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

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

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

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

参考#

• Docker buildx 文档
• 阿里云容器镜像服务 ACR
• Compose healthcheck
• Twelve-Factor App

昇哥 · 2026年4月 my-resume 从 v2.2.0 跑到 v2.2.13 途中，把踩过的坑写下来

下一篇，会是 AI 实战的开始—— 不是部署，是真正让简历”活起来”的那部分。