3.4 KiB
3.4 KiB
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Troubleshooting wiki_revision: d9d5da6c3644a3004a7d55c5e9beda7c3aeaa679 synchronized_at: 2026-09-10T11:37:58Z
故障排查
排查顺序
| 现象 | 判断与处理 | 成功条件 |
|---|---|---|
| 没有产品启动入口 | 当前仅文档阶段，先完成 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 大小警告来自当前选用工具链，不影响已验证构建；生产体积优化不作为本单完成条件。
supervisor 中管理端编译完成但 HTTP 请求超时
本机首次接入时，Vue CLI 已打印 App running at，但子进程停在 pnpm --version，主进程同步等待版本检查，页面和 API 代理均超时。同一命令在普通终端可正常返回页面。已在 lexgo-admin 实例中设置 environment=npm_config_manage_package_manager_versions="false"，阻止这次检查自动切换 pnpm 版本，重新创建实例后首页 200、API 鉴权 401 验证通过。该环境变量仅作用于此实例；项目依赖仍按锁文件和明确版本安装。
排查时同时查看 D:/supervisord/lexgo-admin_out.log、lexgo-admin_err.log，核对端口占用者及其子进程。Running 只说明进程存活，仍需检查首页和 /api/v1/me。具体启动与配置更新方式见 Local-Development-and-Verification。