feat: 无头运行器 Docker 镜像

把 runner/ 打包成可直接部署的容器镜像,Linux 服务器 / 群晖 / 云主机上
不用再手动装 Node 与浏览器。

- Dockerfile:node:22-bookworm-slim + 官方 google-chrome-stable。
  刻意不用发行版 chromium —— 它不带 H.264/AAC 专有编解码器,课程视频会
  一直停在 0 秒;同时满足 preflight.mjs 对 Node 22+ 的硬性要求。
  构建期完成 npm ci + npm run build,并实跑一次 headless 验证浏览器可用;
  CHROME_DEB_URL 构建参数供国内换镜像源。
- docker/entrypoint.sh:建 profile / 日志目录;首参为 sh/node 等时直接 exec
  便于排查;无参数且无凭据时降级成 --check,避免容器无意义重启空转。
- docker-compose.yml:挂载 ./.run-profile 与 ./run-logs,shm_size 512m,
  init: true,日志轮转。restart 用 on-failure:3 而非 always —— 运行器刷完课
  会以 0 正常退出,always 会造成「刷完 → 重启 → 再刷完」的热循环。
- .dockerignore:排除 node_modules / .run-profile / run-logs / .env,
  凭据不进镜像层。
- .env.example:账号模板;.gitignore 加 !.env.example 白名单。
- .gitattributes:*.sh / Dockerfile / docker-compose.yml 强制 LF —— 带 CRLF
  时 shebang 会变成 "/bin/sh\r",容器启动直接 exec format error。
- scripts/check.mjs:静态检查扩展到容器入口,跑 sh -n 并对 CRLF 报错
  (Windows 无 sh 时只校验行尾)。29 个文件全绿。
- README:新增「容器(Docker)」小节,含 build / 自检 / run / compose 流程
  与 8 条注意事项(卷权限、/dev/shm、沙箱、验证码、时区、退出码与重启策略)。
This commit is contained in:
void committed 2026-10-26 22:02:08 +08:00
1 parent 65bf63ea6a
commit b588b1042f
9 files changed
+319 -4

No files matched your search

+97
View File
@@ -0,0 +1,97 @@
# 云学堂助手 · 无头运行器镜像
#
# 设计要点(为什么是这些选择):
# · 基础镜像用 node:22-bookworm-slim —— runner/ 依赖全局 WebSocket / fetch,
# preflight.mjs 会硬性要求 Node 22+,低于这个版本连预检都过不去;
# · 浏览器装官方 google-chrome-stable,而不是 Debian 的 chromium:
# 发行版 chromium 不带 H.264/AAC 专有编解码器,课程视频会一直停在 0 秒
# (README「无图形环境常见的坑」里那条 error.code=4 就是这个原因);
# · 构建在镜像内完成(npm ci → npm run build),产物落在 /app 根目录,
# 所以镜像可以直接跑,不依赖宿主机先 build;
# · 容器内必然没有 DISPLAY,运行器会自动走无头;以 root 运行时
# platform.mjs / browser.mjs 会自动补 --no-sandbox 与 --disable-dev-shm-usage,
# 不需要在命令行里手写这些参数。
#
# 构建:docker build -t yun-xue-tang-assistant .
# 运行:见 docker-compose.yml 或 README「容器(Docker)」
FROM node:22-bookworm-slim
# 国内或内网环境从 dl.google.com 下不动时,可用内网镜像 / 本地文件替换:
# docker build --build-arg CHROME_DEB_URL=https://your-mirror/google-chrome-stable_current_amd64.deb .
# 留空则按架构自动取官网地址。
ARG CHROME_DEB_URL=
# tzdata 让日志时间戳跟随 TZ(默认给上海时区);fonts-noto-cjk 只影响截图观感,
# 但缺了它中文在页面里是方块,排查问题时不方便
ENV TZ=Asia/Shanghai \
DEBIAN_FRONTEND=noninteractive
# 注意:这段 RUN 里不要夹注释行——Docker 解析续行时可能把注释当成命令的一部分,容易把命令拼断。
# 步骤:装基础包 → 按架构下官方 Chrome deb → 用 apt 一次装齐依赖 → 清缓存 → 验证能起来。
# procps 提供 ps:运行器启动时靠它找「占着本 profile 的残留浏览器」并收掉(缺了也可跑,自愈会退化)。
RUN set -eux; \
apt-get update; \
apt-get install -y --no-install-recommends \
ca-certificates \
curl \
fonts-liberation \
fonts-noto-cjk \
gnupg \
procps \
tzdata \
wget; \
arch="$(dpkg --print-architecture)"; \
case "$arch" in \
amd64) chrome_deb="google-chrome-stable_current_amd64.deb" ;; \
arm64) chrome_deb="google-chrome-stable_current_arm64.deb" ;; \
*) echo "不支持的架构:$arch(可用 amd64 / arm64)" >&2; exit 1 ;; \
esac; \
chrome_url="${CHROME_DEB_URL:-https://dl.google.com/linux/direct/${chrome_deb}}"; \
echo "下载 Chrome:$chrome_url"; \
wget -q -O /tmp/chrome.deb "$chrome_url"; \
apt-get install -y --no-install-recommends /tmp/chrome.deb; \
rm -f /tmp/chrome.deb; \
rm -rf /var/lib/apt/lists/*; \
dpkg-query -W -f='chrome ${Version}\n' google-chrome-stable; \
timeout 60 google-chrome-stable --headless=new --no-sandbox --disable-gpu \
--disable-dev-shm-usage --dump-dom about:blank > /dev/null
WORKDIR /app
# 依赖层单独缓存:只有 lockfile 变了才重装。
# devDependencies 里的 esbuild 是构建注入脚本必需的,所以不能用 --omit=dev;
# 留着它也能让使用者在容器里直接 `npm run build`
COPY package.json package-lock.json ./
RUN npm ci --no-audit --no-fund
# 业务源码 + 构建脚本 + 无头运行器(node_modules / .run-profile / run-logs / .env 由 .dockerignore 排除)
COPY . .
# 构建注入浏览器用的单文件脚本,并确认产物真的生成了
RUN npm run build && test -s yun-xue-tang-assistant.user.js
# 运行期目录:profile(含登录 cookie)与日志。用命名卷 / 绑定挂载覆盖即可持久化
RUN mkdir -p /app/.run-profile /app/run-logs && chmod 700 /app/.run-profile
COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
# 用 tr 去掉可能存在的 CR(Windows 上检出后容易带 CRLF,shebang 会变成 /bin/sh\r,exec 直接报 exec format error),
# 然后当场用 sh -n 验一遍语法,把问题拦在构建阶段
RUN tr -d '\r' < /usr/local/bin/docker-entrypoint.sh > /tmp/ep.sh \
&& mv /tmp/ep.sh /usr/local/bin/docker-entrypoint.sh \
&& chmod +x /usr/local/bin/docker-entrypoint.sh \
&& sh -n /usr/local/bin/docker-entrypoint.sh
# 容器里没有图形会话,强制无头;面板需要 TTY,后台跑时保持关闭
# (`docker run -it -e YUN_XUE_TANG_TUI=1` 可以打开面板)
ENV YUN_XUE_TANG_HEADLESS=1 \
YUN_XUE_TANG_TUI=0 \
YUN_XUE_TANG_PROFILE_DIR=/app/.run-profile \
YUN_XUE_TANG_LOG_FILE=/app/run-logs/headless.log \
YUN_XUE_TANG_CHROME_BIN=/usr/bin/google-chrome-stable
# 凭据只走环境变量,不在镜像里 ENV(否则会被写进镜像层):
# docker run ... -e YUN_XUE_TANG_USR=账号 -e YUN_XUE_TANG_PWD=密码
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
# 默认无参数:入口脚本在「没参数且没填凭据」时自动降级成 --check(只读自检)
CMD []