xiaoshu-app/docs/operations/admin-request-reliability-2026-11-13.md

管理后台间歇失败修复（2026-11-13）

用户报告会员管理、排课中心和新增排课出现 0 Unknown Error 或“请求暂未完成，结果待核对”。本次只修小树；用户明确要求不修改不确定归属的公共服务 server.fmode.cn。

证据与边界

• HTTPS 证书有效期为 2026-11-05 至 2027-02-03，预检请求 CORS 正常，排除了既往证书过期故障。
• 真实接口捕获读取超时、HTTP 503 HTML 响应，以及网关内部 Parse SDK 收到 HTML 后的 JSON 解析错误。首次混合来源诊断课表 37.959 秒；按前端实际 source: database 重测，课表 9.455–13.222 秒、会员列表 4.135–4.291 秒。不能把混合来源样本当作前端同条件基线。
• 小树应用进程持续运行，数据库采样没有锁等待；共享 2 核主机负载曾达到 11.21，同时有其他批处理竞争资源、其他公共服务反复重启及入口连接拒绝。这些是共享基础设施风险，本次未修改其他服务、进程优先级、负载均衡、DNS 或公共 Nginx 配置。
• 小树的服务端 Parse SDK 使用公网 https://server.xiaoshu.pro/parse 访问自身，内部查询会额外经过存在间歇故障的公网链路。此问题在本次范围内修复。修复不代表公共入口的所有 503 已从根源消除。

已发布的修改

1. 小树专属配置 config/config.xiaoshu.json 的 parse.serverURL 改为 http://127.0.0.1:10337/parse。同时切换该小树进程的 Parse SDK 和 global.Config，无需重启。publicServerURL、其他配置、凭据及公共服务保持原值。线上回读确认只有内部 URL 变化，进程 PID 未变。
2. 管理端只对明确列入白名单的读取请求，在 HTTP 0/502/503/504 后等待 500ms 重试一次。20 秒客户端超时不会重试；写入和未知操作绝不自动重放。等待重试期间退出或更换账号也会停止重试。
3. 区分读取失败与提交结果不确定，去掉裸露的接口地址和 Unknown Error，保留表单；提交连接失败提示先核对，避免重复操作。固定操作名称，禁止参数覆盖导致读写分类错误。

验证

• 新增回归测试先失败再通过；管理端全量 385 项、内部路由配置测试 2 项通过。生产构建成功，保留既有样式体积和 CommonJS 警告。
• 独立代码审查通过；补齐同时恢复文件与运行时值的回退模式。
• 内部配置修改后连续 9 次正式接口读取均成功：课表 6.455–11.620 秒、会员 2.015–3.521 秒、版本 0.645–1.383 秒。共享负载变化会影响样本，此处不作受控性能提升比例声明。
• 正式浏览器验证：课表首次断连后重试成功；会员列表首次注入 503 后重试成功；排课日期切换连续两次断连后，草稿保留、显示读取错误，恢复后错误清除。真实排课预检通过，1 节可排、0 冲突。本次未创建预约、充值或扣费。
• 发布 admin-reliability-5e391e414c72-20261113T124722803Z，代码提交 5e391e414c7232fff8f248386ba2de55e1adc73e；96 个公网文件哈希与深路由回读一致，CDN 刷新 8184630812 完成。
• 临时诊断函数已清理。原始诊断、备份和验收收据位于本机受限目录 /Users/mac/.local/state/xiaoshu/qa/2026-11-13-admin-errors/，不纳入 Git。

回退与后续

内部配置可用 scripts/repair-admin-internal-routing.mjs --check 获取当前校验值；如需回退，使用 --rollback EXPECTED_SHA256 BACKUP_PATH。备份路径保存在受限发布收据中；回退同时恢复配置文件和运行时 SDK，不重启进程。脚本仅允许目标应用、端口和对外地址匹配，且无无关配置变化时执行。

静态站点基线保存在上述私有目录的 admin/baseline。公共服务崩溃、共享资源隔离及公共入口健康检查仍需对应维护方处理；不能将小树侧验收通过表述为整个共享基础设施故障已彻底修复。