fix(docs): 按 mx-core v14.15.2 实况核对并修正全站文档 - #50
Merged
Merged
Conversation
以 mx-space/core v14.15.2 源码为唯一依据，对全站 53 份文档做事实核对。
所有结论均已回到源码复核，三条关键结论由两条独立路径交叉印证。
P0 修复（用户照做会失败/静默失效）：
部署 6 条——照原文档部署根本起不来
- source.mdx / update.mdx 的 pm2 配置改为 ecosystem.config.cjs。apps/core 的
package.json 声明 type: module，.js 会被当 ESM，文档示例里的 require() 未定义，
PM2 启动即崩
- out/index.js 不存在，vite 的 entryFileNames 是 [name].mjs，真实产物是 out/main.mjs
- 三处环境变量示例补 SNOWFLAKE_WORKER_ID，非 dev 未设置时服务端直接 throw
- 删除 docker.mdx 里 MongoDB 时代的 DB_HOST=mongo
- 外部服务的 pnpm prod:pm2 在仓库根不存在，且读不到用户自建配置，改为 pm2 restart
- docker.mdx 的 environment 示例对齐真实的 x-mx-env 锚点结构（映射而非列表）
webhook.mdx：29 个事件名全部过时
v14.0.0 起事件名从 POST_CREATE 改为 post.create，服务端按精确值匹配，写错会被静默
丢弃且不报错。改为点号形式并按 core 的 BusinessEvents 枚举补全到 60 个，另补
EventScope 的 3 种组合作用域，并给出 GET /webhooks/events 作为权威查询入口。
encryption.mdx：删掉指向不存在脚本的进阶小节
文档让用户跑 src/migration/helper/encrypt-configs.ts，但 apps/core/src/migration/
整个目录不存在、全仓 0 命中。同时收窄加密范围——v14.15.2 全 schema 只有
oauth.secrets 一处标记 encrypt: true，图床密钥、SMTP 密码、AI 密钥都不加密。
其余 P0
- environment.mdx 补 MX_PUSH_RELAY_ORIGINS（不配即抛 Push Relay origin is not allowed）
- account-security.mdx：禁用密码登录的硬前提是至少一个 Passkey，OAuth 不能替代
（PasskeyPanel.tsx 强制校验 passkeys.length > 0）
- ai-features.mdx：Provider 类型枚举过时（OpenAI/OpenRouter 已并入 openai-compatible），
删除 core 中不存在的 3 个「自动生成」开关，补 4 个缺失的 AI 子系统
- content.mdx：页面排序方向写反了，实际是 asc(pages.order)
- faq.mdx：本地文件 URL 是 /api/v3/objects 而非 /static；删除 core 中不存在的
JWT_SECRET is required 报错
- backup-restore.mdx：备份路径是 ~/.mx-space/backup；改写恢复流程（服务端已有直接
回滚 API，无需手工重命名）
- files.mdx：{ext} 含前导点，示例会产生双扩展名；{timestamp} 是毫秒级
第 2 批——后台菜单路径全站重写（23 个文件 50+ 处）
apps/admin 就在 core 仓库内，路径可全量核实。真实导航是「设置」（不是「设定」）且为
分组式：设置 → 站点 → SEO、设置 → 账号安全 → OAuth 登录 等。依据是
configs.dsl.util.ts 的 groupConfigs 与 zh-CN.ts 的文案表。对侧边栏分组名无源码依据的
顶级页面，改用已验证的路由标题而非猜测分组前缀。
第 3 批——环境变量表重写
原表 21 键、源码约 45 键。补齐 Redis 连接串、集群、调试、遥测、推送中继、高级变量
等分组，并标注 REDIS_URL 等别名优先级。同时修正三处不准确：DISABLE_CACHE 是空壳
选项、ENCRYPT_ENABLE 设了密钥就隐式开启、TZ 的来源是 compose 而非 core。
第 4 批——新增 v13→v14 升级指南
此前 v14 在全站只出现 1 次（反向代理里的一条 Callout），而 core 已在 v14.15.2。新页
覆盖 v14.0.0 的两个 breaking change（socket.io → 原生 WebSocket、事件名点号化）、
官方要求的部署顺序、v14 期间全部 5 次 schema 迁移（含「schema 不最新则拒绝启动」），
以及 v14.8/v14.12/v14.14.3/v14.15.0/v14.15.1 的接口与配置移除清单。已接入
migrate/index 与 use/update 两处导航。
额外：public/agent-skills/*.md 三处过时（/api/v2 → v3、NestJS 11 → 12、
后台 Vue 3 + Naive UI → React 19 SPA）。该目录被 robots.txt 放行并由 deploy/agent.mdx
指引 AI 代理读取，错误的版本信息会直接误导使用者。
验证：pnpm build 56 页零警告 · pnpm check 0 error · pnpm lint 通过 · pnpm pangu 通过 ·
check-links 0 阻塞断链
SafeDep Report Summary
No dependency changes detected. Nothing to scan. This report is generated by SafeDep GitHub App |
上一轮提交信息写了「修正全站文档」，审计后发现仍有同类残留：文档在教用户配置
源码里根本不存在的东西。这类错误的危害与已修的 P0 同级，不能留着让提交信息变成
过度声明。
主题文档里的 API 前缀是真实故障（此前完全漏检）
kami.mdx、yun.mdx、shiro/extra.mdx 的配置示例让用户把 API 地址填成 /api/v2，
照抄在 v13+ 上直接失效。已改为 /api/v3。
注意：migrate/v12-to-v13.mdx 里的 /api/v2 是正确的历史引用（该文讲的正是
v2 → v3 的切换），已逐条确认后保留，未做无差别替换。
v11 → v12 指南的 pm2 文件名同样是错的
经 GitHub API 核验 v12.0.0 的 apps/core/package.json 已是 "type": "module"，
且该版本仓库里的文件就叫 ecosystem.config.cjs。也就是说这份迁移指南从写下
起就是错的，照做会撞上和 v14 一样的 ESM 崩溃。修正 6 处。
Cloudflare Tunnel 整节
文档让用户在容器内设置 ENABLE_CLOUDFLARED 和 CF_ZERO_TRUST_TOKEN 拉起隧道，
并教用户去日志里确认 "Starting Cloudflared Tunnel" 横幅。这两个变量在当前
服务端源码中零命中，镜像也不再内置 cloudflared，横幅永远不会出现。改写为
在宿主机自行运行 cloudflared 并说明后果。
后台路径与文案（补上上一轮漏掉的）
- 移除 4 处 proxy_set_header REMOTE-HOST：服务端 IP 解析链不读这个头
（X-Real-IP 与 X-Forwarded-For 保留，这两个确实被读取）
- deploy/index.mdx 自相矛盾：正文说「四种部署方式」但表格与卡片只有 3 种，
num={4} 也对不上；一并删除指向不存在的 /docs/deploy/one-script 的死链
- oauth.mdx 补 Sign in with Apple（配置结构与 GitHub/Google 完全不同，
是 Services ID + Team ID + Key ID + .p8 + Bundle ID），并给出回调地址的
真实形状 {API地址}/auth/callback/{provider}
- account-security.mdx 改用后台原文「主人账户」
- image-storage.mdx 补 {y} {h} {i} {s} 四个占位符；修正 S3 字段中文名；
移除「访问密钥（加密存储）」的误导（该字段不在加密范围内）
- serverless.mdx 补 Skill 类型、内置 5 个云函数、函数的 Redis/PG 存储能力、
通配路由的 1000/5s 限流；修正公开访问 URL（/api/v3/snippets/* 其实是
需鉴权的后台管理接口，公开入口是 /api/v3/s/*）
- cron-tasks.mdx 补「重置 App Review 演示数据」任务
- ssl.mdx 的 listen 443 ssl http2 改为 listen 443 ssl + http2 on
（nginx ≥ 1.25.1 已废弃前者，会稳定输出弃用警告）
验证：pnpm build 56 页零警告 · pnpm check 0 error · pnpm lint 通过 ·
pnpm pangu 通过 · check-links 0 阻塞（站内死链由 2 条降至 1 条，
移除的是指向不存在页面的 /docs/deploy/one-script）
上一轮我断言「只有 OAuth 的 client secret 会被加密，图床密钥、SMTP 密码、AI 密钥都不加密」，并据此删掉了 image-storage.mdx 里原本正确的「（加密存储）」标注。 这个结论是错的，已回源码核实并更正。 错在哪：我是靠 grep 字面量 `encrypt: true` 判断的，在 configs.schema.ts 里只命中 1 处（oauth.secrets）。但绝大多数密码类字段是用 field.password() / field.passwordHalfGrid() 定义的，这两个 helper（configs.zod-schema.util.ts:84-110） 会通过 withMeta 注入 encrypt: true，字面量搜索根本看不到。共 19 个字段走这条路， 其中就包括 S3 / R2 的 secretKey（configs.schema.ts:217、230）。 另外 configs.encrypt.util.ts:97 的判定是 `meta?.encrypt || parentEncrypt`， 父级被标记时整棵子树继承加密——说明加密范围本就比我推断的宽。 本次更正 - encryption.mdx：改写「哪些字段会被加密」一节，说明注入规则与父级继承，给出按 区域归类的实际覆盖范围（OAuth / 图床 / 邮件 / AI / Webhook / 搜索推送 / 会员 / 其他） - image-storage.mdx：恢复「访问密钥（加密存储）」，并移除我上一轮加的那条错误告警 - environment.mdx：补 JWT_EXPIRE（app.config.ts:97、248，默认 14 天）——上一轮 重建整张表时漏了 - agent-skills/mix-space-expert.md：仍留「设定 → AI 设定」旧路径。上一轮的批量 替换只覆盖了 content/docs，漏了 public/ 下的 AI 知识面，已改为 「设置 → AI → AI 设置」 - AGENTS.md：更新当前状态，记录核对基线是 tag v14.15.2 之后 9 个提交的 master （commit def0803），并列出已按源码定论的项，避免下次重新推导 数字更正：webhook 事件表是 59 个，不是 60。已按 core 的 BusinessEvents 枚举逐条 比对，文档表格行数与枚举值数一致，均为 59。 门禁：pnpm build 56 页零警告 · pnpm check 0 error · pnpm lint 通过 · pnpm pangu 通过 · check-links 0 阻塞
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.