feat: 构建更新

deploy/Dockerfile.server

@@ -1,14 +1,16 @@
 # 在 Linux 内安装依赖和生成 Prisma 客户端，不能复用开发机的 node_modules。
 FROM node:24.20.0-bookworm-slim AS base
+# 按构建网络选择 npm 源；不修改开发机配置，也不改变锁定依赖版本。
+ARG NPM_REGISTRY=https://registry.npmjs.org
 RUN apt-get update \
     && apt-get install -y --no-install-recommends ca-certificates openssl \
     && rm -rf /var/lib/apt/lists/* \
-    && npm install --global pnpm@11.24.0
+    && npm install --global pnpm@11.24.0 --registry="${NPM_REGISTRY}"
 WORKDIR /app
 
 FROM base AS build
 COPY . .
-RUN pnpm install --frozen-lockfile --filter @doodle/server...
+RUN pnpm install --frozen-lockfile --filter @doodle/server... --registry="${NPM_REGISTRY}"
 RUN pnpm --filter @doodle/server... run build
 
 FROM base AS runtime

docs/v3.5/服务端首次部署操作手册.md

@@ -109,6 +109,22 @@ docker buildx build \
 
 Docker 内部安装项目锁定的 Node.js 24.20.0 / pnpm 11.24.0，构建 contracts、生成 Linux Prisma 客户端，再编译 NestJS。不会使用 Mac 的 `node_modules`，也不需要提供真实数据库密码、微信或七牛密钥来构建。
 
+如果 `pnpm install` 从 npm 官方源下载依赖时持续超时，可通过构建参数切换到 [npmmirror 国内镜像源](https://npmmirror.com/)：
+
+```bash
+docker buildx build \
+    --platform linux/amd64 \
+    --progress=plain \
+    --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
+    -f deploy/Dockerfile.server \
+    -t doodle-server:20261022-01 \
+    --load .
+```
+
+该参数同时用于安装 pnpm 和安装项目依赖；默认仍使用 npm 官方源，不修改 Mac 的全局 npm 配置或锁文件。保留 `--frozen-lockfile` 及依赖完整性校验。仅在 Mac 上执行 `npm config set registry` 不会自动修改 Docker 构建环境中的源。
+
+此参数只控制 npm 包下载，不控制 Docker Hub 基础镜像、Debian apt 软件源和 Prisma 独立引擎下载。如果镜像源尚未同步指定版本，或错误发生在其他下载域名，需要按完整日志另行处理。
+
 确认镜像架构并导出：
 
 ```bash
@@ -139,16 +155,40 @@ chmod 700 /opt/doodle/prod
 
 如果文件页隐藏点文件，打开显示隐藏文件后编辑 `.env`。若通过网页上传大镜像超时，可改用 1Panel 支持的分片上传，或用已有 SSH/SFTP 上传；无需改用浏览器将镜像作为 SQL 文件导入。
 
-在 **1Panel 终端**执行：
+建议在导入前通过 **1Panel 终端**校验上传文件：
 
 ```bash
 cd /opt/doodle/releases/20261022-01
 sha256sum -c doodle-server-20261022-01.tar.gz.sha256
-docker image load -i doodle-server-20261022-01.tar.gz
-docker image inspect doodle-server:20261022-01 --format '{{.Os}}/{{.Architecture}} {{.Id}}'
 ```
 
-校验输出必须为 `OK`；否则重新上传。`docker load` 已将镜像导入服务器本机 Docker，后续 Compose 从本机使用该镜像，无需再从镜像仓库下载。
+校验输出应为 `OK`；否则重新上传。SHA-256 校验不是部署必需步骤，但建议保留，以便提前发现上传不完整的问题。
+
+### 4.1 通过图形界面导入（推荐）
+
+1. 进入 **1Panel → 容器 → 镜像 → 导入镜像**。
+2. 选择已上传到服务器的 `/opt/doodle/releases/20261022-01/doodle-server-20261022-01.tar.gz`，确认导入。
+3. 如果导入界面不接受 `.tar.gz`，先通过 **1Panel → 文件**将其解压成 `.tar`，再选择该 `.tar` 文件导入。
+4. 导入完成后，在镜像列表确认存在标签 **`doodle-server:20261022-01`**。
+
+使用图形界面导入后，不需要再执行 `docker load`。镜像已经保存在服务器本机 Docker 中，后续 Compose 可直接使用，无需再从镜像仓库下载。
+
+**导入镜像不等于启动服务。** 接下来仍需按第 5 节填写 `server.env`，再按第 6 节通过 Compose 创建、启动 API 容器。
+
+### 4.2 命令行导入（备选）
+
+如果不使用图形界面，也可在 **1Panel 终端**执行以下命令，二选一即可：
+
+```bash
+cd /opt/doodle/releases/20261022-01
+docker image load -i doodle-server-20261022-01.tar.gz
+```
+
+无论采用哪种导入方式，都可以用以下命令补充检查镜像架构和 ID：
+
+```bash
+docker image inspect doodle-server:20261022-01 --format '{{.Os}}/{{.Architecture}} {{.Id}}'
+```
 
 ## 5. 填写服务器配置