故障排查

进程无法启动

检查日志、端口选择、目录属主与数据库连接。原生进程和容器默认端口不同。/etc/secrets 资源格式错误或数据库升级失败都可能阻止启动。不要通过删库或强行更改结构版本来消除错误，排查前先保留副本。

页面正常但操作失败

登录问题应检查外部地址、HTTPS、Cookie 与身份提供方回调。上传问题应检查应用及代理大小限制和存储凭据。笔记缺失时，清除筛选并检查账号、空间和归档。unavailable 错误应检查数据库容量，并仅在安全时重试。

集成失败

确认请求指向应用而非官网。检查令牌过期或撤销状态，以及操作使用的资源名称。Webhook 接收端必须返回有效 JSON 与符合要求的响应，不能只有空的成功状态。MCP 客户端需要支持 Streamable HTTP，并发现本服务实际提供的工具。

有效的问题报告

提供源码或构建版本、部署方式、时间、脱敏错误、复现步骤和预期结果。移除令牌、Cookie、数据库连接信息、提供方密钥与私人笔记内容。说明是本地也会失败，还是仅通过代理失败。浏览器截图可能无法揭示服务端错误。

第一轮具体排查命令

默认本地 Docker 部署中，先采集状态、近期日志及直连健康响应，再改配置。容器退出应查看启动日志；容器运行却连接被拒，应检查端口与绑定；直连健康而公开入口失败，应排查代理路径。日志可能包含用户内容，分享前需要去敏。不要直接粘贴完整 docker inspect 输出，因为环境字段可能含有秘密。

docker inspect memos --format 'status={{.State.Status}} exit={{.State.ExitCode}}'
docker port memos
docker logs --since 10m --tail 100 memos
curl --verbose --max-time 10 http://127.0.0.1:5230/healthz

按错误选择下一项测试

只测试出现故障的层级，保留原始数据。API 错误应同时阅读 HTTP 状态及结构化错误；404 也可能用于隐藏无权访问的资源。记录脱敏错误，不要关闭权限检查。