From 0f53088ffeeba7d244be314ecb69fd433fa007fa Mon Sep 17 00:00:00 2001 From: "cnb.dQC5J6ohAGA" <8m0v8c12sZDrY2infddElF+cnb.dQC5J6ohAGA@noreply.cnb.cool> Date: Thu, 17 Sep 2026 10:16:11 +0800 Subject: [PATCH] =?UTF-8?q?fix(docker):=20=E5=85=81=E8=AE=B8=E9=9D=9E=20ro?= =?UTF-8?q?ot=20=E7=94=A8=E6=88=B7=E5=86=99=E5=85=A5=E6=8C=82=E8=BD=BD?= =?UTF-8?q?=E7=9A=84=20/data?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 服务端以非特权用户 `reader` 运行，镜像里构建时做的 `chown /data` 在 `/data` 被 **挂载** 时完全失效：bind mount 的属主来自宿主机目录，宿主机上 `./data` 不存在时 Docker 会以 root:root 新建它，于是服务端写签名密钥时 直接以 `EACCES: permission denied, open '/data/token.secret'` 崩溃退出。 命名卷继承镜像的 chown，所以只有 bind mount 受影响，而 compose 与 README 推荐的正是 bind mount，等于默认路径就是坏的。 改动： - 新增 `server/docker-entrypoint.sh`：以 root 启动，只在启动时把 /data 这一层的属主改成 reader（不递归整棵树，避免大缓存目录每次重启都被 chown），随后用 su-exec 降权到 reader 再 exec 服务端。服务端仍是 pid 1， main.ts 的 SIGTERM/SIGINT 优雅退出照常工作。若容器本来就不是 root 启动（`--user`），脚本直接 exec 命令，不尝试改属主。 - `server/Dockerfile`：装 su-exec（约 10KB；alpine 的 busybox 没有等价的 setpriv，util-linux 又不在基础镜像里），加 ENTRYPOINT。去掉 `USER reader`， 因为降权改由入口脚本完成。 - `server/src/config/index.ts`：写密钥失败时，EACCES/EPERM/EROFS 不再只抛 errno，而是报出「DATA_DIR 必须可写」并给出两种修法（改宿主机属主， 或设 READER_TOKEN_SECRET 跳过写文件）。这是自部署最高频的坑， 直接给出下一步能省掉一整轮排查。 - 新增 `server/test/config.test.ts`：覆盖密钥持久化与复用的稳定性、 READER_TOKEN_SECRET 优先时不落盘、目录不可写时错误信息含修法、 DATA_DIR 落在 BOOKS_DIR 内被拒。权限用例在非 root 下运行， 以 root 跑测试时跳过。 - README 增加「故障排查」小节，写明成因与 4 步自查。 验证：`npm run typecheck` 通过；`npm test` 149 项 148 通过 1 跳过 （跳过项即需非 root 的权限用例，已用非 root 单独跑通）；以非 root 手动 复现 EACCES 路径，确认错误信息与修法正确；入口脚本的 chown + 降权流程 手动模拟通过。 --- README.md | 37 ++++++++++ server/Dockerfile | 15 +++- server/docker-entrypoint.sh | 45 ++++++++++++ server/src/config/index.ts | 17 ++++- server/test/config.test.ts | 132 ++++++++++++++++++++++++++++++++++++ 5 files changed, 243 insertions(+), 3 deletions(-) create mode 100755 server/docker-entrypoint.sh create mode 100644 server/test/config.test.ts diff --git a/README.md b/README.md index e66c866..4b54039 100644 --- a/README.md +++ b/README.md @@ -319,6 +319,43 @@ EPUB 永远留在 WebView：文字排版是差异点，只能有一份实现。 --- +## 故障排查 + +### 启动即退出：`EACCES: permission denied, open '/data/token.secret'` + +``` +fatal: Error: EACCES: permission denied, open '/data/token.secret' + at loadOrCreateSecret (file:///app/dist/config/index.js:27:5) +``` + +`/data` 挂上了，但容器里的服务进程写不进去。服务端以非特权用户 `reader` +（uid/gid `100:100`）运行，而 `/data` 若是 **bind mount**（`./data:/data`）， +挂载点的属主来自宿主机目录，**会覆盖镜像里构建时做的 chown**——宿主机上 +`./data` 不存在时 Docker 会以 `root:root` 新建它，于是非特权用户写不了。 +命名卷（named volume）继承镜像里的 chown，不受影响。 + +镜像的入口脚本已经会在启动时自动把 `/data` 的属主改成 `reader` 再降权运行， +所以**正常用官方镜像不会遇到这个问题**。仍然报错时按顺序检查： + +1. 拉的是最新镜像：`docker compose pull && docker compose up -d`。 +2. 自己加了 `user:` / `docker run --user` 覆盖了启动用户，去掉它。 +3. `/data` 所在文件系统不支持改属主（NFS / SMB / NTFS 挂载，如群晖的部分共享目录）， + 此时给 `READER_TOKEN_SECRET` 设一个 ≥16 字符的随机串，服务端就不需要写密钥文件： + ```bash + openssl rand -base64 48 # 生成一个 + ``` + 在 compose 里加 `READER_TOKEN_SECRET: "<上面的值>"`。 +4. 手动修宿主机目录属主（Linux；群晖等 NAS 上 uid 可能不同）： + ```bash + sudo chown -R 100:100 ./data + ``` + +> 自建的镜像若来自 `server/Dockerfile`，注意 `ENTRYPOINT` 不能被覆盖，否则降权 +> 那一步不会执行。服务端本身在写密钥失败时会直接报出「`DATA_DIR` 必须可写」 +> 并给出一键修法，不会再只抛一个 errno。 + +--- + ## 让外网访问（内网穿透 / 域名 / HTTPS） 自部署最大的门槛在这里，所以单独说清楚。三种常见做法： diff --git a/server/Dockerfile b/server/Dockerfile index d64fb9f..70b9f86 100644 --- a/server/Dockerfile +++ b/server/Dockerfile @@ -52,7 +52,12 @@ ENV NODE_ENV=production \ # Run as an unprivileged user. The library mount is read-only, so this user only # ever needs write access to /data. -RUN addgroup -S reader && adduser -S reader -G reader \ +# +# `su-exec` is a ~10KB static helper that drops privileges from an entrypoint; +# Alpine's busybox has no equivalent (`setpriv` lives in util-linux, which the +# base image does not carry), and `su` there needs a password hash to be set up. +RUN apk add --no-cache su-exec \ + && addgroup -S reader && adduser -S reader -G reader \ && mkdir -p /data /books /app/public && chown -R reader:reader /data /books /app/public COPY --from=build --chown=reader:reader /app/node_modules ./node_modules @@ -61,7 +66,12 @@ COPY --from=build --chown=reader:reader /app/package.json ./ # The built H5 client, served by the same process at `/`. COPY --from=web --chown=reader:reader /web/dist ./web -USER reader +# The entrypoint starts as root purely to take ownership of the *mounted* /data +# (a bind mount's uid/gid comes from the host and overrides the chown above), +# then re-execs the server as `reader`. See the script for the full rationale. +COPY --chown=root:root server/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh +RUN chmod 0755 /usr/local/bin/docker-entrypoint.sh + EXPOSE 8080 VOLUME ["/data"] @@ -70,4 +80,5 @@ VOLUME ["/data"] HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||8080)+'/api/v1/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))" +ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"] CMD ["node", "dist/main.js"] diff --git a/server/docker-entrypoint.sh b/server/docker-entrypoint.sh new file mode 100755 index 0000000..7c09d00 --- /dev/null +++ b/server/docker-entrypoint.sh @@ -0,0 +1,45 @@ +#!/bin/sh +# Fix the ownership of the writable data directory before dropping privileges. +# +# Why this exists: the image runs as the unprivileged `reader` user, and the +# build-time `chown /data` is useless the moment `/data` is *mounted*. A bind +# mount (`./data:/data`) exposes the host directory's own uid/gid, which on Linux +# is almost always root:root — the chown baked into the image never applies to a +# mount, only to the image layer underneath it. Docker creates a *missing* bind +# source as root:root too, so the very common +# +# docker compose up -d # ./data does not exist yet +# +# lands on a root-owned `/data`, and the server then dies at boot with +# +# EACCES: permission denied, open '/data/token.secret' +# +# because `loadOrCreateSecret` cannot write the signing key. +# +# Named volumes inherit the image's chown, so they were never affected — this +# only repairs bind mounts, and only the directory itself (not the whole tree), +# so a big library cache is not re-chowned on every restart. +# +# The entrypoint therefore stays root just long enough to take ownership of the +# single directory the server writes to, then `exec`s the server as `reader` so +# the long-running process keeps the unprivileged uid. +set -e + +DATA_DIR="${DATA_DIR:-/data}" + +if [ "$(id -u)" = "0" ]; then + mkdir -p "$DATA_DIR" + # `chown` on the directory alone is enough: SQLite, the cover cache and the + # secret are all created *inside* it by the server, which then owns them. + # Failures are tolerated (e.g. a read-only data mount) so the server can still + # start and report a clearer error of its own. + chown reader:reader "$DATA_DIR" 2>/dev/null || true + + # Drop to the unprivileged user for the long-running process. `su-exec` is the + # alpine-native equivalent of gosu; it sets uid/gid and exec's, so the server + # keeps pid 1 and still receives SIGTERM (see main.ts shutdown handling). + exec su-exec reader:reader "$@" +fi + +# Already non-root (e.g. `docker run --user`): just run the command. +exec "$@" diff --git a/server/src/config/index.ts b/server/src/config/index.ts index b87ffd7..425527d 100644 --- a/server/src/config/index.ts +++ b/server/src/config/index.ts @@ -76,7 +76,22 @@ function loadOrCreateSecret(dataDir: string, file = 'token.secret'): string { if (existing.length >= 16) return existing; } const generated = randomBytes(48).toString('base64url'); - writeFileSync(secretPath, generated, { mode: 0o600 }); + try { + writeFileSync(secretPath, generated, { mode: 0o600 }); + } catch (err) { + // A bare EACCES here is the single most common self-hosting failure: /data + // is a bind mount whose host directory is root-owned while the server runs + // as an unprivileged user. Say so, instead of surfacing a bare errno. + const code = (err as NodeJS.ErrnoException).code; + if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') { + throw new Error( + `cannot write ${secretPath} (${code}); DATA_DIR must be writable by the server. ` + + `If /data is a bind mount, fix its ownership on the host (e.g. \`chown -R 100:100 ./data\`) ` + + `or set READER_TOKEN_SECRET to a value of at least 16 characters to skip the file entirely.`, + ); + } + throw err; + } return generated; } diff --git a/server/test/config.test.ts b/server/test/config.test.ts new file mode 100644 index 0000000..74db85d --- /dev/null +++ b/server/test/config.test.ts @@ -0,0 +1,132 @@ +/** + * Config-loading tests, focused on the failure mode that breaks a plain + * `docker compose up` on a fresh checkout. + * + * The image runs the server as an unprivileged user, so a bind-mounted `/data` + * whose host directory is root-owned makes the signing-key write fail with a + * bare `EACCES`. These tests pin down both the happy path and the *explained* + * error, because a raw errno here is what turns a one-line fix into a support + * thread. + */ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtemp, mkdir, readFile, chmod, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { loadConfig } from '../src/config/index.ts'; + +const SECRET_ENV = ['READER_TOKEN_SECRET', 'JWT_SECRET'] as const; + +async function withEnv( + vars: Record, + fn: () => Promise | void, +): Promise { + const saved = new Map(); + for (const key of [...SECRET_ENV, 'DATA_DIR', 'BOOKS_DIR']) { + saved.set(key, process.env[key]); + delete process.env[key]; + } + Object.assign(process.env, vars); + try { + await fn(); + } finally { + for (const [key, value] of saved) { + if (value === undefined) delete process.env[key]; + else process.env[key] = value; + } + } +} + +test('a fresh DATA_DIR gets a persisted, stable secret', async () => { + const root = await mkdtemp(join(tmpdir(), 'reader-config-')); + const dataDir = join(root, 'data'); + const booksDir = join(root, 'books'); + await mkdir(booksDir, { recursive: true }); + + try { + await withEnv({ DATA_DIR: dataDir, BOOKS_DIR: booksDir }, async () => { + const first = loadConfig(); + assert.ok(first.jwtSecret.length >= 16, 'secret is long enough to sign with'); + + // Written 0600: the key is a credential, not world-readable config. + const stat = await readFile(join(dataDir, 'token.secret'), 'utf8'); + assert.equal(stat.trim(), first.jwtSecret); + + // A second boot must reuse it, or every client session would be dropped + // on restart. + const second = loadConfig(); + assert.equal(second.jwtSecret, first.jwtSecret); + }); + } finally { + await rm(root, { recursive: true, force: true }); + } +}); + +test('READER_TOKEN_SECRET wins and skips the file entirely', async () => { + const root = await mkdtemp(join(tmpdir(), 'reader-config-')); + const dataDir = join(root, 'data'); + const booksDir = join(root, 'books'); + await mkdir(booksDir, { recursive: true }); + + try { + await withEnv( + { DATA_DIR: dataDir, BOOKS_DIR: booksDir, READER_TOKEN_SECRET: 'a-secret-set-by-the-operator' }, + async () => { + const config = loadConfig(); + assert.equal(config.jwtSecret, 'a-secret-set-by-the-operator'); + // Nothing to persist, so no file is created. + await assert.rejects(readFile(join(dataDir, 'token.secret'), 'utf8')); + }, + ); + } finally { + await rm(root, { recursive: true, force: true }); + } +}); + +test('an unwritable DATA_DIR fails with the fix, not a bare EACCES', async (t) => { + if (process.getuid?.() === 0) { + // root bypasses the permission bits, so the failure cannot be reproduced. + t.skip('running as root; permission bits are not enforced'); + return; + } + + const root = await mkdtemp(join(tmpdir(), 'reader-config-')); + const dataDir = join(root, 'data'); + const booksDir = join(root, 'books'); + await mkdir(dataDir, { recursive: true }); + await mkdir(booksDir, { recursive: true }); + await chmod(dataDir, 0o500); + + try { + await withEnv({ DATA_DIR: dataDir, BOOKS_DIR: booksDir }, async () => { + assert.throws( + () => loadConfig(), + (err: unknown) => { + const message = err instanceof Error ? err.message : String(err); + assert.match(message, /cannot write .*token\.secret/); + assert.match(message, /DATA_DIR must be writable/); + // The escape hatch is spelled out, so the reader has a way forward. + assert.match(message, /READER_TOKEN_SECRET/); + return true; + }, + ); + }); + } finally { + await chmod(dataDir, 0o700); + await rm(root, { recursive: true, force: true }); + } +}); + +test('DATA_DIR inside BOOKS_DIR is refused at boot', async () => { + const root = await mkdtemp(join(tmpdir(), 'reader-config-')); + const booksDir = join(root, 'books'); + await mkdir(booksDir, { recursive: true }); + + try { + await withEnv({ DATA_DIR: join(booksDir, 'data'), BOOKS_DIR: booksDir }, () => { + assert.throws(() => loadConfig(), /must not live inside BOOKS_DIR/); + }); + } finally { + await rm(root, { recursive: true, force: true }); + } +});