OPC/lexgo

Table of Contents

故障排查

排查顺序
必须停止的情况
工程基础常见问题（#2）
supervisor 中管理端编译完成但 HTTP 请求超时

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

故障排查

排查顺序

现象	判断与处理	成功条件
没有产品启动入口	当前仅文档阶段，先完成 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。