lexgo/docs/06-troubleshooting.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting wiki_revision: 139b4b3c61a26143577a8450a6abf53965737534 synchronized_at: 2026-09-10T09:38:20Z

故障排查

排查顺序

现象	判断与处理	成功条件
没有产品启动入口	当前仅文档阶段，先完成 M0 和工程创建	有真实构建/运行命令后更新验证页
MCP 看不到 LexGo	当前 MCP 指向其他站点；以用户确认的 git.ilapage.cn 为准	API 能读取 OPC/lexgo
新 Wiki 列表 404	先确认仓库存在且 has_wiki=true；未初始化时创建 Home 并回读	Home 有正文和 revision
sync 拒绝脏镜像	检查并保存合法本地修改，不覆盖现有改动	提交/妥善保存后重试
check 缺少标题或映射	补齐真实主题和显式映射	check --strict 通过
数据库方案冲突	用户已确定 MySQL 8，历史 PostgreSQL 建议被覆盖	档案和新方案一致

必须停止的情况

目标仓库身份不清时停止远端写入；页面无法回读、无 revision 或同步失败时停止产品编码。数据越权、破坏性操作超出授权时停止相关操作。独立文档整理可以继续。

工程基础常见问题（#2）

• Go 工具链提示 GOSUMDB=off：scripts/server.py 仅在子进程启用 sum.golang.org 校验并固定 go1.26.5，不修改全局 go env。原理见 https://go.dev/doc/toolchain 。
• Windows 执行上游类 Unix 环境变量脚本失败：使用本项目 admin/package.json 的跨平台脚本，保留 Vue CLI，不直接调用原始源码目录中的脚本。
• 本地接口受到系统代理影响：访问 loopback；PowerShell 验证可用 Invoke-WebRequest -NoProxy。测试仅对 loopback 追加 NO_PROXY，不关闭其他网络代理。
• 原生前端依赖下载停滞：本次安装指定官方 npm registry 后成功；锁文件已生成，不更改全局 registry。不要通过关闭包完整性检查解决安装问题。
• serve 报需先迁移：核对 LEXGO_DB_NAME，显式执行 migrate；未知产品或版本必须先诊断，不手工植入 marker 绕过保护。
• 登录失效：重新登录；账号停用或重置密码会撤销全部会话。用户名不是邮箱，区分格式错误与凭据失败。
• 管理端构建中的 Sass 旧 API 弃用和 vendor 大小警告来自当前选用工具链，不影响已验证构建；生产体积优化不作为本单完成条件。