MJ-IT/gdm-Servo-model
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DEPLOY_STATIC.md 文档补强：增加 npm 镜像源与 named volume 提示 #2

New Issue
Closed
opened 2026-08-17 12:40:19 +08:00 by hukeehong · 2 comments
hukeehong commented 2026-08-17 12:40:19 +08:00
Owner
Copy Link

背景

在阿里云 ECS 上按 DEPLOY_STATIC.md "构建静态文件" 章节执行一次性容器 build 时，首次 build 卡了 5 分钟超时未结束，需要文档补强。

Issue #1 已 closed（部署完成），这个是新发现的环境层问题，单独开 issue。

问题

DEPLOY_STATIC.md 当前推荐的构建命令：

docker run --rm \
  -v "$PWD":/src \
  --tmpfs /src/node_modules \
  -w /src \
  node:22-alpine \
  sh -lc 'npm ci && npm run build:static'

在阿里云 ECS 上有两个实际问题：

1. 官方 npm registry 连不上（导致 build 卡死）

服务器在阿里云网络，官方 https://registry.npmjs.org/ 经常连不上。npm ci 会持续重试到超时，体感是 build 卡住。

实测对比：

  • curl https://registry.npmjs.org/vite → 超时 10 秒
  • curl https://registry.npmmirror.com/vite → 2.3 秒完成，HTTP 200

切到阿里云镜像后，npm ci && npm run build:static 整体 5 秒搞定。

2. --tmpfs /src/node_modules 默认 noexec，导致 esbuild postinstall 失败

之前尝试过 --tmpfs 方式，esbuild 的 postinstall binary (/src/node_modules/esbuild/bin/esbuild) 会报 EACCES、spawnSync EACCES。

原因是 tmpfs 默认 mount 选项是 noexec，可执行文件没法跑。

建议修改

A. 在 "构建静态文件" 章节前面加一步

# 中国大陆服务器建议先切 npm 镜像源（官方源经常连不上）
npm config set registry https://registry.npmmirror.com

B. 把 --tmpfs /src/node_modules 替换成 named docker volume

把：

--tmpfs /src/node_modules

改成：

-v duoji-node-modules:/src/node_modules

理由：

  • 避免 noexec 问题
  • named volume 可以跨多次 build 复用 node_modules，npm ci 更快
  • volume 在 docker volume rm duoji-node-modules 时才销毁，不会污染宿主机

C. "后续更新" 章节的 build 命令也加同样修改

文档末尾的更新流程里 docker run ... 那段是同样的命令，需要同步改。

验证

应用文档修改后：

# 1. 切镜像源
npm config set registry https://registry.npmmirror.com

# 2. build（首次会慢，10-30 秒；后续 build 因 volume 缓存会很快）
time docker run --rm -v "$PWD":/src -v duoji-node-modules:/src/node_modules -w /src \
  node:22-alpine sh -lc 'npm ci && npm run build:static'

预期：build 整体 30 秒内完成（首次），3-5 秒完成（volume 缓存命中后）。

不需要做的事

  • 不要改 Dockerfile.static —— 它是独立服务器场景，跟这次问题无关
  • 不要改 deploy/nginx-static.conf —— 同上
  • 不要把 npm 镜像源写进仓库配置文件（避免影响非中国大陆环境）

（实施层反馈，跟 Issue #1 是同一个上下文但不同问题。Issue #1 是部署方案整体，这个是文档细节。）

## 背景 在阿里云 ECS 上按 `DEPLOY_STATIC.md` "构建静态文件" 章节执行一次性容器 build 时，**首次 build 卡了 5 分钟超时未结束**，需要文档补强。 Issue #1 已 closed（部署完成），这个是新发现的环境层问题，单独开 issue。 --- ## 问题 `DEPLOY_STATIC.md` 当前推荐的构建命令： ```bash docker run --rm \ -v "$PWD":/src \ --tmpfs /src/node_modules \ -w /src \ node:22-alpine \ sh -lc 'npm ci && npm run build:static' ``` 在阿里云 ECS 上有两个实际问题： ### 1. 官方 npm registry 连不上（导致 build 卡死） 服务器在阿里云网络，**官方 `https://registry.npmjs.org/` 经常连不上**。`npm ci` 会持续重试到超时，体感是 build 卡住。 实测对比： - `curl https://registry.npmjs.org/vite` → 超时 10 秒 - `curl https://registry.npmmirror.com/vite` → 2.3 秒完成，HTTP 200 切到阿里云镜像后，`npm ci && npm run build:static` 整体 5 秒搞定。 ### 2. `--tmpfs /src/node_modules` 默认 noexec，导致 esbuild postinstall 失败 之前尝试过 `--tmpfs` 方式，esbuild 的 postinstall binary (`/src/node_modules/esbuild/bin/esbuild`) 会报 `EACCES`、`spawnSync EACCES`。 原因是 `tmpfs` 默认 mount 选项是 `noexec`，可执行文件没法跑。 --- ## 建议修改 ### A. 在 "构建静态文件" 章节前面加一步 ```bash # 中国大陆服务器建议先切 npm 镜像源（官方源经常连不上） npm config set registry https://registry.npmmirror.com ``` ### B. 把 `--tmpfs /src/node_modules` 替换成 named docker volume 把： ```bash --tmpfs /src/node_modules ``` 改成： ```bash -v duoji-node-modules:/src/node_modules ``` 理由： - 避免 `noexec` 问题 - named volume 可以跨多次 build 复用 `node_modules`，npm ci 更快 - volume 在 `docker volume rm duoji-node-modules` 时才销毁，不会污染宿主机 ### C. "后续更新" 章节的 build 命令也加同样修改 文档末尾的更新流程里 `docker run ...` 那段是同样的命令，需要同步改。 --- ## 验证 应用文档修改后： ```bash # 1. 切镜像源 npm config set registry https://registry.npmmirror.com # 2. build（首次会慢，10-30 秒；后续 build 因 volume 缓存会很快） time docker run --rm -v "$PWD":/src -v duoji-node-modules:/src/node_modules -w /src \ node:22-alpine sh -lc 'npm ci && npm run build:static' ``` 预期：build 整体 30 秒内完成（首次），3-5 秒完成（volume 缓存命中后）。 --- ## 不需要做的事 - 不要改 `Dockerfile.static` —— 它是独立服务器场景，跟这次问题无关 - 不要改 `deploy/nginx-static.conf` —— 同上 - 不要把 npm 镜像源写进仓库配置文件（避免影响非中国大陆环境） --- （实施层反馈，跟 Issue #1 是同一个上下文但不同问题。Issue #1 是部署方案整体，这个是文档细节。）
jacky commented 2026-08-17 14:36:24 +08:00
Collaborator
Copy Link

建议同步补强首次构建和后续更新命令：

  1. 通过 npm_config_registry 支持切换 npm 镜像，默认使用 https://registry.npmmirror.com，不写入仓库配置，避免影响非中国大陆环境。
  2. 将 --tmpfs /src/node_modules 改为 Docker named volume，避免 tmpfs 默认 noexec 导致 esbuild 执行失败。
  3. 额外挂载 /root/.npm 缓存卷，加快后续依赖安装。
  4. 文档中说明 npm ci 会重建 node_modules：named volume 主要用于隔离并解决执行权限问题，缓存加速由 npm cache volume 负责。
  5. 首次构建和“后续更新”章节使用同一套命令，并补充 docker volume rm duoji-node-modules 和 docker volume rm duoji-npm-cache 的清理方法。

建议命令示例：

docker run --rm -v "$PWD":/src -v duoji-node-modules:/src/node_modules -v duoji-npm-cache:/root/.npm -w /src -e npm_config_registry=https://registry.npmmirror.com node:22-alpine sh -lc 'npm ci --no-audit --no-fund && npm run build:static'

建议同步补强首次构建和后续更新命令： 1. 通过 npm_config_registry 支持切换 npm 镜像，默认使用 https://registry.npmmirror.com，不写入仓库配置，避免影响非中国大陆环境。 2. 将 --tmpfs /src/node_modules 改为 Docker named volume，避免 tmpfs 默认 noexec 导致 esbuild 执行失败。 3. 额外挂载 /root/.npm 缓存卷，加快后续依赖安装。 4. 文档中说明 npm ci 会重建 node_modules：named volume 主要用于隔离并解决执行权限问题，缓存加速由 npm cache volume 负责。 5. 首次构建和“后续更新”章节使用同一套命令，并补充 docker volume rm duoji-node-modules 和 docker volume rm duoji-npm-cache 的清理方法。 建议命令示例： docker run --rm -v "$PWD":/src -v duoji-node-modules:/src/node_modules -v duoji-npm-cache:/root/.npm -w /src -e npm_config_registry=https://registry.npmmirror.com node:22-alpine sh -lc 'npm ci --no-audit --no-fund && npm run build:static'
hukeehong commented 2026-08-18 10:21:01 +08:00
Author
Owner
Copy Link

已采纳，更新完成 ✅

按你的建议改完了，commit fb2a346 Document npm registry mirror and Docker named volumes for builds。

采纳的 5 点（对应你的建议 #1-#5）：

  1. npm_config_registry 环境变量 而非 npm config set，默认不传；非中国大陆环境不受影响 ✓
  2. duoji-node-modules named volume 替代 --tmpfs ✓
  3. 额外挂载 duoji-npm-cache 到 /root/.npm ✓
  4. 文档里说明了 npm ci 会重建 node_modules：named volume 主要解决 noexec 和隔离问题，缓存加速由 /root/.npm 卷负责 ✓
  5. 首次构建和后续更新用同一套命令 ✓，并补充了 docker volume rm duoji-node-modules / docker volume rm duoji-npm-cache 清理方法 ✓

额外补的两个点：

  • --no-audit --no-fund：跳过 npm 审计和赞助，加快部署速度
  • 把"caddy reload 不重挂 bind mount"写进了"与现有 Caddy 共存"章节，提醒以后改 compose 必须重启容器

部署验证

服务器上跑了新命令验证：

docker volume create duoji-node-modules
docker volume create duoji-npm-cache
docker run --rm -v "$PWD":/src \
  -v duoji-node-modules:/src/node_modules \
  -v duoji-npm-cache:/root/.npm \
  -w /src \
  -e npm_config_registry=https://registry.npmmirror.com \
  node:22-alpine \
  sh -lc "npm ci --no-audit --no-fund && npm run build:static"

实际耗时 38 秒（npm ci 33s + build 5.7s），产物 120M，rsync 到 /var/www/duoji/ 后 https://duoji.dbpi.com.cn/ 200，gdm.dbpi.com.cn 和 wisdomplay.dbpi.com.cn 均不受影响。容器无重启（只换了静态文件）。

下次更新可以走"后续更新"章节那套命令，预计 npm ci 在 volume 缓存命中后会降到几秒。

## 已采纳，更新完成 ✅ 按你的建议改完了，commit `fb2a346 Document npm registry mirror and Docker named volumes for builds`。 采纳的 5 点（对应你的建议 #1-#5）： 1. **`npm_config_registry` 环境变量** 而非 `npm config set`，默认不传；非中国大陆环境不受影响 ✓ 2. **`duoji-node-modules` named volume** 替代 `--tmpfs` ✓ 3. **额外挂载 `duoji-npm-cache`** 到 `/root/.npm` ✓ 4. **文档里说明了 `npm ci` 会重建 node_modules**：named volume 主要解决 `noexec` 和隔离问题，缓存加速由 `/root/.npm` 卷负责 ✓ 5. **首次构建和后续更新用同一套命令** ✓，并补充了 `docker volume rm duoji-node-modules` / `docker volume rm duoji-npm-cache` 清理方法 ✓ 额外补的两个点： - `--no-audit --no-fund`：跳过 npm 审计和赞助，加快部署速度 - 把"caddy reload 不重挂 bind mount"写进了"与现有 Caddy 共存"章节，提醒以后改 compose 必须重启容器 ## 部署验证 服务器上跑了新命令验证： ```bash docker volume create duoji-node-modules docker volume create duoji-npm-cache docker run --rm -v "$PWD":/src \ -v duoji-node-modules:/src/node_modules \ -v duoji-npm-cache:/root/.npm \ -w /src \ -e npm_config_registry=https://registry.npmmirror.com \ node:22-alpine \ sh -lc "npm ci --no-audit --no-fund && npm run build:static" ``` 实际耗时 38 秒（npm ci 33s + build 5.7s），产物 120M，rsync 到 `/var/www/duoji/` 后 `https://duoji.dbpi.com.cn/` 200，`gdm.dbpi.com.cn` 和 `wisdomplay.dbpi.com.cn` 均不受影响。容器无重启（只换了静态文件）。 下次更新可以走"后续更新"章节那套命令，预计 npm ci 在 volume 缓存命中后会降到几秒。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
hukeehong jacky
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: MJ-IT/gdm-Servo-model#2
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?