feat(comments): Artalk 部署配置化 — site.commentsProvider 驱动 + 镜像拆分

- Docker 镜像拆分 prod / prod-artalk(内置 Artalk 二进制)与 dev / dev-artalk,
  docker-compose 用 VANBLOG_IMAGE_TAG 选择镜像
- 内置 Artalk 是否启动改由持久化的 site.commentsProvider 决定,弃用
  VANBLOG_ARTALK_ENABLED 环境变量开关
- /setup 首次初始化可选启用 Artalk:自动生成 artalk.yml 并创建管理员账号
- 新增 /api/vanblog/runtime/comments 就绪探针,entrypoint.prod.sh 据此拉起内置 Artalk
- setup/status 暴露 capabilities.artalk(镜像是否带二进制),前端据此禁用选项
- Caddy 仅当 commentsProvider=artalk 时生成 /comments/* 反向代理路由
- SDK setup.complete 扩展 comments 字段;docs 新增 comments-system.md 架构总览,
  comments-artalk.md / configuration.md / faq.md / features / demo 同步更新

Author: CornWorld

Dockerfile

@@ -129,17 +129,10 @@ WORKDIR /app
 # Install Caddy + Node.js (for Astro SSR) + ca-certificates
 RUN apk add --no-cache caddy nodejs ca-certificates tzdata curl
 
-# Artalk (self-hosted comment system) — optional sidecar, enabled at runtime
-# via VANBLOG_ARTALK_ENABLED=1. Downloaded at build time so the image is
-# reproducible. Override the version with --build-arg ARTALK_VERSION=vX.Y.Z.
-# NOTE: if Artalk changes its release asset naming, update the URL below.
-ARG ARTALK_VERSION=v2.10.0
-RUN mkdir -p /tmp/artalk && \
-    curl -fsSL "https://github.com/ArtalkJS/Artalk/releases/download/${ARTALK_VERSION}/artalk_${ARTALK_VERSION}_linux_amd64.tar.gz" -o /tmp/artalk/artalk.tar.gz && \
-    tar -xzf /tmp/artalk/artalk.tar.gz -C /tmp/artalk && \
-    find /tmp/artalk -type f -name 'artalk' -exec mv {} /usr/local/bin/artalk \; && \
-    chmod +x /usr/local/bin/artalk && \
-    rm -rf /tmp/artalk
+# Artalk is provided by the separate prod-artalk target.
+# image intentionally has no Artalk binary; prod-artalk adds it below.
+
+
 
 # Copy Go binary and the separately-built core schema artifact.
 COPY --from=go-build /pocketbase /usr/local/bin/vanblog
@@ -195,7 +188,18 @@ VOLUME ["/pb_data", "/data/caddy", "/data/artalk"]
 
 ENTRYPOINT ["/entrypoint.sh"]
 
-# --- Stage 6: DEV image (extends prod + full Node toolchain + source) ---
+# --- Stage 6: PROD image with bundled Artalk capability ---
+FROM prod AS prod-artalk
+ARG ARTALK_VERSION=v2.10.0
+RUN apk add --no-cache curl && \
+    mkdir -p /tmp/artalk && \
+    curl -fsSL "https://github.com/ArtalkJS/Artalk/releases/download/${ARTALK_VERSION}/artalk_${ARTALK_VERSION}_linux_amd64.tar.gz" -o /tmp/artalk/artalk.tar.gz && \
+    tar -xzf /tmp/artalk/artalk.tar.gz -C /tmp/artalk && \
+    find /tmp/artalk -type f -name 'artalk' -exec mv {} /usr/local/bin/artalk \; && \
+    chmod +x /usr/local/bin/artalk && \
+    rm -rf /tmp/artalk
+
+# --- Stage 7: DEV image (plain prod capability) ---
 FROM prod AS dev
 
 RUN apk add --no-cache npm git && npm install -g pnpm@latest-10
@@ -242,3 +246,25 @@ ENV VANBLOG_MODE=dev
 EXPOSE 80 443 4321 8080
 
 ENTRYPOINT ["/entrypoint.sh"]
+
+# Development image with bundled Artalk capability.
+FROM prod-artalk AS dev-artalk
+RUN apk add --no-cache npm git && npm install -g pnpm@latest-10
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml .npmrc /workspace/
+COPY sdk/ /workspace/sdk/
+COPY app/ /workspace/app/
+COPY packs/ /workspace/packs/
+COPY themes/ /workspace/themes/
+COPY scripts/ /workspace/scripts/
+COPY models.config.mjs /workspace/models.config.mjs
+COPY docs/ /workspace/docs/
+COPY AGENTS.md /workspace/AGENTS.md
+COPY .pi/ /workspace/.pi/
+COPY .agents/ /workspace/.agents/
+WORKDIR /workspace
+RUN pnpm install --frozen-lockfile
+COPY docker/entrypoint.dev.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+ENV VANBLOG_MODE=dev
+EXPOSE 80 443 4321 8080
+ENTRYPOINT ["/entrypoint.sh"]

app/src/pages/setup.astro

@@ -62,6 +62,17 @@ if (alreadySetup) {
       <input name="passwordConfirm" type="password" required autocomplete="new-password" minlength="8"
              class="px-1.5 py-0.5" />
     </label>
+    <fieldset class="border p-3 mt-3">
+      <legend>评论系统（可选）</legend>
+      <label class="flex items-center gap-2"><input name="commentsProvider" type="radio" value="disabled" checked /> 不启用 Artalk</label>
+      <label class="flex items-center gap-2"><input name="commentsProvider" type="radio" value="artalk" /> 启用内置 Artalk</label>
+      <div id="artalk-setup" class="hidden flex flex-col gap-2 mt-2">
+        <input name="artalk_site" type="text" value="VanBlog" placeholder="Artalk Site 名" />
+        <input name="artalk_email" type="email" autocomplete="email" placeholder="Artalk 管理员邮箱" />
+        <input name="artalk_password" type="password" autocomplete="new-password" minlength="8" placeholder="Artalk 管理员密码（至少 8 位）" />
+        <input name="artalk_password_confirm" type="password" autocomplete="new-password" minlength="8" placeholder="确认 Artalk 管理员密码" />
+      </div>
+    </fieldset>
     <input type="hidden" name="back" value={back} />
     <button type="submit" class="self-start px-3 py-1">创建管理员</button>
     <p id="setup-error" class="text-red-600 text-sm hidden"></p>
@@ -73,6 +84,19 @@ if (alreadySetup) {
     const form = document.getElementById('setup-form');
     const errEl = document.getElementById('setup-error');
     const statusEl = document.getElementById('setup-status');
+    const artalkSetup = document.getElementById('artalk-setup');
+    const providerInputs = form.querySelectorAll('[name="commentsProvider"]');
+    const setupStatus = self.vanblog?.pb?.vanblog?.setup;
+    setupStatus?.status?.().then((status) => {
+      const artalk = form.querySelector('[value="artalk"]');
+      if (!status.capabilities?.artalk && artalk) {
+        artalk.disabled = true;
+        artalk.parentElement.title = '当前镜像不包含 Artalk，请使用 prod-artalk 镜像';
+      }
+    }).catch(() => {});
+    providerInputs.forEach((input) => input.addEventListener('change', () => {
+      artalkSetup.classList.toggle('hidden', input.checked && input.value === 'artalk');
+    }));
 
     form.addEventListener('submit', async (e) => {
       e.preventDefault();
@@ -95,6 +119,13 @@ if (alreadySetup) {
           email: fd.get('email'),
           password: fd.get('password'),
           passwordConfirm: fd.get('passwordConfirm'),
+          comments: {
+            provider: fd.get('commentsProvider') || 'disabled',
+            artalkSite: fd.get('artalk_site') || 'VanBlog',
+            artalkEmail: fd.get('artalk_email') || '',
+            artalkPassword: fd.get('artalk_password') || '',
+            artalkPasswordConfirm: fd.get('artalk_password_confirm') || '',
+          },
         });
         if (r.ok) {
           statusEl.textContent = '✓ 管理员创建成功，正在跳转登录…';

docker-compose.yml

@@ -26,7 +26,8 @@
 
 services:
   vanblog:
-    image: ghcr.io/cornworld/vanblog:prod-edge
+    # 选择 prod(不含 Artalk) 或 prod-artalk(含 Artalk 能力，默认仍关闭):
+    image: ghcr.io/cornworld/vanblog:${VANBLOG_IMAGE_TAG:-prod}
     # 本地构建: build: { context: ., target: prod }
     restart: unless-stopped
     ports:
@@ -39,16 +40,21 @@ services:
       - caddy_data:/data/caddy
       - pack_data:/var/lib/vanblog/packs
       - themes_data:/var/lib/vanblog/themes
-      # Artalk 内置 sidecar 数据(启用 VANBLOG_ARTALK_ENABLED=1 时持久化评论):
+      # Artalk 数据(仅 prod-artalk 镜像启用内置 Artalk 时使用):
       - artalk_data:/data/artalk
+      # 若要自行维护配置文件，可取消注释(会覆盖自动生成):
+      # - ./artalk.yml:/data/artalk/artalk.yml:ro
     environment:
       - VANBLOG_EMAIL=${VANBLOG_EMAIL:-admin@example.com}
       - VANBLOG_CADDY_LOG_LEVEL=${VANBLOG_CADDY_LOG_LEVEL:-warn}
       - VANBLOG_PACKS_DIR=/var/lib/vanblog/packs
       - VANBLOG_THEMES_DIR=/var/lib/vanblog/themes
       # --- Artalk 评论系统 ---
-      # 内置 sidecar(单容器,默认推荐):
-      # - VANBLOG_ARTALK_ENABLED=1
+      # 选择 prod-artalk 后，在 /setup 向导中选择是否启用并填写 Artalk 账号。
+      # 这里只保留外部 Artalk upstream；它不负责启用状态:
+      # - VANBLOG_ARTALK_UPSTREAM=artalk:23366
+      # SSO 桥接开关(可选，默认关闭):
+      # - VANBLOG_COMMENTS_SSO_ENABLED=1
       # 外部 Artalk 容器(compose 多容器,配合下面 artalk 服务):
       # - VANBLOG_ARTALK_UPSTREAM=artalk:23366
       # HTTP_ONLY 模式:外置反代终止 TLS(取消注释即生效):
@@ -58,7 +64,7 @@ services:
       # - PB_URL=http://127.0.0.1:8090
 
   # --- Artalk 评论系统(compose 多容器模式,可选)---
-  # 默认推荐内置 sidecar(vanblog 服务设 VANBLOG_ARTALK_ENABLED=1)。
+  # 默认推荐 prod-artalk 镜像；是否启用内置 Artalk 在 /setup 向导中选择。
   # 若要 Artalk 独立容器(独立升级/解耦生命周期),取消下面注释,
   # 并在 vanblog 服务里设 VANBLOG_ARTALK_UPSTREAM=artalk:23366。
   # artalk:

docker/entrypoint.prod.sh

@@ -87,13 +87,26 @@ vanblog serve "$@" &
 PB_PID=$!
 wait_for "http://127.0.0.1:8090/api/health" "PocketBase" 30 || exit 1
 
-# 3.5. Start Artalk comment sidecar (optional; enabled via VANBLOG_ARTALK_ENABLED=1)
-if [ "${VANBLOG_ARTALK_ENABLED}" = "1" ] || [ "${VANBLOG_ARTALK_ENABLED}" = "true" ]; then
-  echo "[vanblog] starting Artalk comment sidecar (port 23366)..."
-  mkdir -p /data/artalk
-  (cd /data/artalk && exec env ATK_HOST=127.0.0.1 ATK_PORT=23366 artalk server) &
-  ARTALK_PID=$!
-  wait_for "http://127.0.0.1:23366/" "Artalk" 30 || exit 1
+# 3.5. Start the bundled Artalk only when the persisted site provider is artalk.
+# The prod image may not contain the binary; prod-artalk does.
+if command -v artalk >/dev/null 2>&1; then
+  COMMENTS_PROVIDER=$(wget -q -O - -T 2 "http://127.0.0.1:8090/api/vanblog/runtime/comments" 2>/dev/null || echo '{"provider":"disabled"}')
+  case "$COMMENTS_PROVIDER" in
+    *'"provider":"artalk"'*)
+      echo "[vanblog] starting bundled Artalk (port 23366)..."
+      ARTALK_DIR="/data/artalk"
+      ARTALK_CONFIG="${ARTALK_DIR}/artalk.yml"
+      mkdir -p "$ARTALK_DIR"
+      if [ ! -f "$ARTALK_CONFIG" ]; then
+        echo "[vanblog] Artalk config not found, generating default: $ARTALK_CONFIG"
+        artalk gen config "$ARTALK_CONFIG"
+      fi
+      (cd "$ARTALK_DIR" && exec env ATK_HOST=127.0.0.1 ATK_PORT=23366 artalk -c "$ARTALK_CONFIG" server) &
+      ARTALK_PID=$!
+      wait_for "http://127.0.0.1:23366/" "Artalk" 30 || exit 1
+      ;;
+    *) echo "[vanblog] bundled Artalk is installed but disabled" ;;
+  esac
 fi
 
 # 4. Start Theme Host (replaces direct Astro SSR)

docs/comments-artalk.md

@@ -1,8 +1,10 @@
 # Artalk 评论系统集成（自托管 + 同源）
 
+> 本文是 Artalk 的**部署操作手册**。评论系统的架构与集成总览（conf 数据流、鉴权边界、provider 模型）见 [`comments-system.md`](./comments-system.md)。
+
 VanBlog 内置 Artalk 评论系统的支持，提供两种部署方式，**都走 Caddy 同源出口 `/comments/*`**，无跨域、无独立 TLS 证书、无额外端口暴露。
 
-- **内置 sidecar（单容器，默认推荐）**：Artalk 进程跑在 VanBlog 容器内，一个开关启用。
+- **内置 Artalk（prod-artalk 镜像）**：镜像带有 Artalk 二进制；是否启动在首次 `/setup` 向导中选择，默认关闭。
 - **compose 多容器（external 接入）**：Artalk 作为独立容器（官方镜像），VanBlog 反代接入。
 
 两种方式共用同一套前端配置和 Caddy 路由生成逻辑。
@@ -19,7 +21,7 @@ Artalk 二进制已内置在 prod 镜像里（构建期下载，`--build-arg ART
 
 ```yaml
 environment:
-  - VANBLOG_ARTALK_ENABLED=1
+  - 选择 `prod-artalk` 镜像，并在首次 `/setup` 向导中启用内置 Artalk
 ```
 
 同时确认 vanblog 服务已挂载 Artalk 数据卷（`docker-compose.yml` 里默认已带）：
@@ -66,7 +68,7 @@ services:
       - VANBLOG_ARTALK_UPSTREAM=artalk:23366
 ```
 
-> 注意：`VANBLOG_ARTALK_UPSTREAM` 优先级高于 `VANBLOG_ARTALK_ENABLED`。外部容器模式下**不要**同时设 `VANBLOG_ARTALK_ENABLED=1`（那会额外启动内置 sidecar）。
+> 注意：`VANBLOG_ARTALK_UPSTREAM` 只表示外部上游地址，不负责启用 Artalk。内置 Artalk 是否启动由 `site.commentsProvider` 决定。
 
 ---
 
@@ -83,10 +85,9 @@ services:
 
 ## Artalk 管理员账号初始化
 
-Artalk 首次部署后不会自动创建管理员。两种方式任选：
+Artalk 管理员不通过命令行初始化。选择 `prod-artalk` 镜像后，首次打开 `/setup` 时可以直接选择启用 Artalk，并填写 Artalk 管理员 email/password；VanBlog 会生成配置并完成账号初始化。
 
-1. **评论框初始化（推荐）**：打开任意文章页评论框，输入管理员用户名和邮箱并提交一条评论，评论框右下角会出现「控制台」按钮，进入 Artalk 管理后台。
-2. **CLI**（内置 sidecar）：`docker exec -it <容器> artalk admin`。
+账号由 `/setup` 向导创建。Artalk 管理员 email 建议与 VanBlog 管理员 email 保持一致，这样后续 SSO 免二次登录可以按 email 映射为 Artalk 管理员。
 
 ---
 
@@ -103,8 +104,76 @@ Artalk 首次部署后不会自动创建管理员。两种方式任选：
 
 ---
 
+## SSO 免二次登录（可选）
+
+VanBlog 提供与 Artalk 的单点登录桥接：博主在 VanBlog 后台点「打开评论管理」，无需再次输入 Artalk 账号密码，直接以管理员身份进入评论管理。
+
+### 原理
+
+复用 Artalk 原生的 `POST /api/v2/sso/exchange` 换票端点：VanBlog 签发一个短期（60 秒）随机 token，Artalk 拿它去 VanBlog 的 `/userinfo` 端点换出登录态。**VanBlog 不持有 Artalk 凭证**，只签发自己控制的短期 token。
+
+### 1. 启用 VanBlog 侧 SSO
+
+在 `docker-compose.yml` 的 `vanblog` 服务环境变量里加：
+
+```yaml
+environment:
+  - VANBLOG_COMMENTS_SSO_ENABLED=1
+```
+
+默认关闭；不设该变量时两个 SSO 端点（`/api/vanblog/comments-sso/*`）不会注册，零攻击面。
+
+### 2. 生成并配置 Artalk
+
+Artalk 提供 `gen config` 命令主动生成默认配置文件：
+
+```bash
+# 在宿主机执行，直接生成当前目录的配置
+artalk gen config ./artalk.yml
+
+# 如果文件已存在，使用 -f 强制覆盖（会丢失已有配置）
+artalk gen config ./artalk.yml -f
+```
+
+也可以在内置 sidecar 的数据卷中生成：
+
+```bash
+docker compose exec vanblog artalk gen config /data/artalk/artalk.yml
+```
+
+然后编辑 `artalk.yml`，至少配置 SSO：
+
+```yaml
+auth:
+  enabled: true
+  sso:
+    enabled: true
+    issuer: "https://<你的域名>/api/vanblog/comments-sso"
+```
+
+管理员账号使用 Artalk 自带命令创建或修改，不需要把密码写进 `artalk.yml`：
+
+```bash
+artalk admin \
+  --name 博主 \
+  --email <你的博主邮箱> \
+  --password '<一个初始密码>'
+```
+
+`--email` **必须与 VanBlog 管理员账号的邮箱一致**。SSO 换票按邮箱找到 Artalk 用户；邮箱一致时，换票用户才能获得 Artalk 管理员身份。
+
+- `issuer` 的域名必须与 VanBlog 的 `baseUrl` 一致，且为 HTTPS（生产环境）。
+- Artalk 会请求 `{issuer}/userinfo`，即 VanBlog 的 `/api/vanblog/comments-sso/userinfo`。
+- `gen config` 默认不会覆盖已有文件；只有明确传 `-f` 才会覆盖。
+
+### 3. 使用
+
+进入 VanBlog 后台 → 站点配置 → 评论，选 `artalk` 并填好 Server 后，点「打开评论管理（免二次登录）」。系统会换票并跳转到博客首页，评论框自动识别管理员身份，右下角出现「控制台」按钮即可进入管理。
+
+---
+
 ## 架构说明
 
 - **Caddy 路由生成**：`vault/internal/caddy/config_builder.go` 的 `buildFullRouteTable` 在系统 API 路由后、用户规则前插入 `/comments/*` 反向代理路由（当 `BuildOpts.ArtalkUpstream` 非空时）。
-- **上游地址**：`vault/internal/caddy/bootstrap.go` 读环境变量 `VANBLOG_ARTALK_UPSTREAM`；为空时若 `VANBLOG_ARTALK_ENABLED=1` 则回退到 `127.0.0.1:23366`。
+- **上游地址**：`vault/internal/caddy/bootstrap.go` 仅在 `site.commentsProvider=artalk` 时生成 Artalk 上游；配置 `VANBLOG_ARTALK_UPSTREAM` 时使用外部实例，否则回退到 `127.0.0.1:23366`。
 - **同源前缀剥离**：Artalk 本身不支持 base path（以 `/` 为根），所以系统路由用 `rewrite strip_path_prefix` 剥掉 `/comments` 前缀后再反向代理。`site.routing` 的 proxy 规则也提供 `stripPathPrefix` 字段，可复用于任意不支持 base path 的上游。