十八中论坛 · 文档 十八中论坛使用说明书

文档 / 十八中论坛使用说明书

博客发包 API 与 Agent / MCP 接入

博客 ZIP / Git 发包、运行配置、MCP Agent 接入与 OAuth 授权；注明未上线和验收边界。

状态：源码已部署，生产整链待验收。2026-10-05（UTC）已部署博客 Agent API、MCP / OAuth 源码及增量迁移；公网发现元数据与未授权 MCP 的 401 边界已验证。Git 隔离出口仍未安装，Git 发布未开放；真实账号授权、ZIP 发布、重部署和回滚未完成生产验收，不能因文档或接口存在就认为全部可用。

本章面向使用脚本或 AI Agent 管理本人博客、访问论坛用户 API 的开发者。普通网页操作见创作者面板，已有 API 契约见API 网关。

先选接入方式

方式 适合谁 鉴权 状态
v1 HTTP API 脚本、CI、直接调用接口 论坛 Bearer API 令牌；第一方页面也可用会话 源码已部署；认证后生产整链待验收
本地 stdio MCP 能在本机启动 Node 进程的 Agent 论坛 Bearer API 令牌 本机验收通过，须连接含新功能的服务
远程 Streamable HTTP MCP 支持 OAuth 的 MCP 客户端 论坛自有 OAuth 源码已部署；发现与未授权 401 已验，真实授权待验

新调用只用 /client/v1/…。不再扩展旧 /r/*、/w/*。MCP 工具从 v1 用户路由生成，排除管理员专用、MC 原生客户端接口和旧 API；没有任意 URL、宿主命令或通用 SSH 执行工具。

令牌与最小权限

每次操作都核对当前账号状态、权限以及博客所有权。先列出本人站点，取得明确的 site_id，不要把用户名当作站点 ID；同一账号的三个博客槽位彼此独立。

能力 内容范围 读写能力
站点、版本及任务查询 blog_read read
下载发布源码包 blog_download read
发布、分片、重部署和回滚 blog_upload write
仓库凭据创建、查询和撤销 显式 blog_credentials 查询为 read，修改为 write
受限 SSH 能力查询 显式 blog_ssh write

blog_credentials、blog_ssh 不会因旧令牌未填写内容范围而自动获得。按任务申请最小权限，不要给只读 Agent 写权限。不要把令牌、私钥或仓库密码提交到代码、聊天记录或日志。

博客 API 端点

除列表外，下表路径均以 /client/v1/blog/sites/{site_id} 为前缀。写操作可使用 Idempotency-Key；重试同一操作必须保持 key、源码、配置和来源一致。第一方会话写请求使用 X-CSRF-Token，不接受 Idempotency-Key。

方法和路径 请求要点 作用
GET /client/v1/blog/sites 无 本人站点列表
GET /releases page、per_page 已发布版本列表
POST /deployments multipart file，可选 config JSON 字符串 上传 ZIP 并发布
POST /deployments/git repository_url，可选 ref、credential_id、config 异步 Git 发布
GET /deployments/{job_id} 任务 ID 查询任务阶段、结果及提交 SHA
POST /redeploy 可选 config 对象 重新部署当前版本源码，不改在线编辑页面
POST /rollback version 回滚到已发布版本，不覆盖 /data
POST /packages size 字节数、sha256 创建 ZIP 暂存包
POST /packages/{package_id}/chunks?byte_offset=0 application/octet-stream 原始字节 写入连续分片
POST /packages/{package_id}/deploy 可选 config 对象 校验完整包后发布
DELETE /packages/{package_id} 无 取消暂存包
GET /download 可选 version 下载发布 ZIP
GET /download/chunks 可选 version、byte_offset 下载有限大小 base64 分片
GET /credentials 无 凭据 ID 与非秘密元数据
POST /credentials name、host、kind、secret，可选 username、host_key 加密保存仓库凭据
DELETE /credentials/{credential_id} 无 撤销凭据并清除密文
POST /ssh 无 查询受限 SSH 连接能力，不执行命令

同步发布成功返回 201；异步受理返回 202 和 job_id。202 只是受理，不是发布成功。 使用任务查询工具或接口检查 queued、fetching、building、checking、switching，直到 success 或 failed。候选失败应保留旧版本；切换成功后才算完成。

ZIP 与分片规则

  • ZIP 最大 50MiB；每个上传分片最多 1MiB。
  • 创建暂存包时先声明完整文件大小及 SHA-256；发布前核对完整文件与摘要。
  • 偏移以字节计数，必须连续写入；完全相同的已写分片可重放，错位或不同内容会拒绝。
  • 暂存包一小时失效；完成后部署，取消时删除。临时清理仅限专用暂存目录。
  • 下载同样按有限分片读取；Agent 不应把完整二进制文件塞进文本回复。

ZIP 配置发布示例

以下是新服务上线后的调用形式；本机测试时将 FORUM18_API_URL 换成自己的测试服务。FORUM18_API_TOKEN 从安全环境注入，不在命令中写真实令牌。

curl --fail-with-body "$FORUM18_API_URL/client/v1/blog/sites/$SITE_ID/deployments" \
  -H "Authorization: Bearer $FORUM18_API_TOKEN" \
  -H "Idempotency-Key: publish-my-site-001" \
  -F 'file=@./site.zip' \
  -F 'config={"runtime":"static","project_dir":".","public_dir":".","entry":"index.html"}'

运行配置

config 可覆盖包内 forum18.json 的运行配置，沿用现有校验，不提供环境变量管理 API。

字段 类型与含义
runtime static、php、node、python
project_dir、public_dir 包内相对目录，默认 .；不接受绝对路径、隐藏路径或 ..
entry 包内入口文件；静态为 HTML / HTM，PHP 为 PHP 文件
php_mode pages、front、router
spa 布尔值，单页应用回退
install、build、start 安装、构建、启动命令；由受控运行时执行，不是宿主命令接口
health_path 候选版本健康检查路径

源码文件、运行配置和持久化 /data 是不同对象。不要把环境秘密打进发布包；也不要把版本回滚当作数据库或持久化数据恢复。

Git 仓库部署与凭据

支持手动触发公开 / 私有 HTTPS 仓库以及 SSH 仓库，不提供 webhook 或自动持续部署。首版只在控制面同节点抓取，连接目标要求公网 IPv4；固定 HTTPS 443、SSH 22，不接受自定义端口。

  • HTTPS URL 例：https://github.com/example/project.git；私有仓库通过 credential_id 指定令牌，不在 URL 嵌入密码。
  • SSH URL 例：ssh://git@example.org/team/project.git；必须指定包含可信主机公钥的 SSH 凭据，不自动接受首次连接的未知密钥。
  • 凭据 kind 为 https 或 ssh，绑定仓库 host；HTTPS secret 为令牌，SSH 为私钥，SSH 另需 host_key。创建后只返回 ID 和元数据，没有秘密回读。
  • ref 可指定分支、tag 或提交 SHA；成功抓取后记录实际提交 SHA。
  • 禁止私网、回环、元数据、宿主及平台节点目标；校验 DNS 后固定连接 IP，拒绝重定向。不关闭 TLS 校验。
  • 固定平台 Git 镜像在硬池和专用出口内运行，不读取宿主 Git / SSH 配置。缺受控主密钥、隔离出口或硬池时拒绝部署。
  • FIFO 限制、最长 900 秒；源码最多 50MiB / 5000 文件，Git 临时数据最多 100MiB。禁用子模块、LFS、hooks，去除 .git 后复用 ZIP 安全检查与发布器。
  • 队列取得执行槽后、连接前再次检查凭据；撤销后拒绝启动，抓取结束仍复核。
{
  "repository_url": "https://github.com/example/project.git",
  "ref": "main",
  "credential_id": 123,
  "config": {"runtime": "static", "public_dir": "dist", "build": "npm run build"}
}

公开 HTTPS 仓库可省略 credential_id。上面的 123 是示例，必须替换成本人该站点的真实凭据 ID。

本地 stdio MCP 配置

需要 Node.js 22+ 和论坛 API 令牌。论坛仓库中的 mcp/ 使用锁定版本的官方 MCP SDK；在目录中运行 npm ci 安装依赖。按客户端格式配置启动程序：

{
  "mcpServers": {
    "forum18": {
      "command": "node",
      "args": ["/absolute/path/to/shibazhong-forum/mcp/server.mjs"],
      "env": {
        "FORUM18_API_URL": "https://api.forum18.cn",
        "FORUM18_API_TOKEN": "<通过客户端安全配置注入论坛令牌>"
      }
    }
  }
}

路径替换为本人已安装仓库的绝对路径。公网地址已接入部署后的源码，但真实账号整链仍待验收；本机测试可使用 loopback HTTP，其余地址须 HTTPS。stdout 仅输出 MCP 协议，日志走 stderr。

常用工具：

工具 用法
blog_sites、blog_releases 列出本人站点及版本
blog_upload_zip_file site_id、用户明确给出的绝对 file_path、可选 config；自动摘要和分片
blog_git 按仓库 URL、ref、凭据及配置提交 Git 部署
blog_redeploy、blog_rollback 重部署或指定版本回滚
blog_deployment 使用 site_id、job_id 查询任务，不等待整个构建
blog_download_zip_file site_id、明确绝对 output_path、可选 version；校验摘要，不覆盖已有文件

普通工具名由 v1 操作 ID 的点替换为下划线。客户端通过 tools/list 获取完整目录、参数类型及读写 / 破坏性标记；不要让 Agent 猜测不存在的工具。

远程 MCP 与 OAuth 授权

服务上线后的远程地址为 https://api.forum18.cn/mcp，沿用 API worker，不增加端口。支持无状态 2026-07-28 HTTP 协议及 2025-11-25 初始化兼容流程，不提供旧 HTTP+SSE 服务。

{"mcpServers":{"forum18":{"url":"https://api.forum18.cn/mcp"}}}

远程只接受论坛自有 OAuth 访问令牌；普通 v1 API 令牌不能调用远程 MCP，OAuth 令牌也不能直接用于 /client/v1。

授权流程为：客户端发现元数据 → 注册 → 使用 Authorization Code + PKCE S256 请求授权 → 论坛登录及已有 2FA → 本人明确选择读写及内容范围 → 交换令牌。默认不勾选全部权限，不授予管理员能力，敏感范围必须显式选择。

入口 作用
API /.well-known/oauth-protected-resource/mcp MCP 资源元数据
主站 /.well-known/oauth-authorization-server 授权服务器元数据
API /oauth/register 受限额的客户端注册
主站 /oauth/authorize.php 登录后的授权或拒绝，POST 带 CSRF
API /oauth/token 授权码交换、刷新轮换
API /oauth/revoke 撤销整组访问 / 刷新令牌
主站 /oauth/grants.php 账号设置中的授权列表与撤销

回调必须精确匹配预注册地址，HTTPS 默认，桌面 loopback 按规则处理。授权码一次性、5 分钟有效；访问令牌 1 小时，刷新令牌 30 天，轮换后旧刷新令牌再次使用会撤销整组授权。令牌绑定客户端、用户、范围及 MCP resource，只存哈希。

远程 ZIP 发布使用 blog_packages_create → blog_packages_chunk（chunk_base64、byte_offset）→ blog_packages_deploy；没有远程任意文件路径读取能力。工具业务失败返回结构化结果及 isError；202 + job_id 后仍须单独查询状态。

验收与上线边界

本机 API 隔离专项 84 项、官方 SDK stdio / 兼容 HTTP、真实 Chrome 登录 / 隔离种子 2FA / 授权 / 拒绝 / 撤销 / 手机布局已通过。新版协议通过直接 HTTP 断言，不代表官方 SDK 新版互通已验。

根测试 PASS 155 / FAIL 0，但日志门禁仍有 42 个基线外指纹，KNOWN / SKIP 不算执行通过。没有删除日志或扩大基线。

尚未验收：本机无 Docker，真实公开 / 私有 HTTPS 和 SSH Git 拉取、错误凭据及主机密钥、Git / ZIP 共用四运行时发布、健康失败保留旧站、重部署 / 回滚 / /data 持久化，以及真实 2FA 投递和生产 HTTPS 整链。

2026-10-05 部署复核（UTC）：源站隔离 API / MCP 84 项通过，公网发现元数据与未授权 401 通过；Git 隔离安装器仅暂存，待管理员 sudo 安装。此前 PASS155/日志42 是本机实现时记录，本次根门禁与日志门禁结果见部署记录；不要把源码上线、离线策略测试或 HTTP 200 当作认证后生产整链可用证明。

这份说明书写得不对、跟不上界面变化？把问题发到论坛举报/反馈，或直接找站长。

十八中论坛 · 文档 · 本页最后更新 2026-10-18