故障排查总表

各平台部署页的每一步后面都附有该步骤的常见错误。本页按现象汇总，找不到对应平台时从这里查。

排查顺序

进程在不在？ Linux systemctl status apexpm / Docker docker compose ps / Windows apexpm-service.exe status / macOS launchctl print gui/$(id -u)/com.apexpm.server
本机能不能访问？ curl -fsS http://127.0.0.1:9000/health
授权正不正常？ curl -fsS http://127.0.0.1:9000/api/v1/license/status
日志里有没有 fatal？ 日志是 JSON，一行一条，找 "level":"fatal" 的那一行，message 说明在哪一步失败，error 说明原因

平台	日志位置
Linux systemd	`journalctl -u apexpm -n 100 --no-pager`
Linux start.sh / deploy.sh	部署目录下的 `apexpm.log`
Docker	`docker compose logs --tail 100`
Windows WinSW	`C:\apexpm\logs\apexpm-service.out.log`
Windows NSSM	`C:\apexpm\logs\apexpm.log`
macOS	`~/apexpm/apexpm.log`

需要更详细的日志时，临时设置环境变量 APEXPM_LOG_LEVEL=debug 后重启。

启动失败

进程启动后立即退出。按日志里 fatal 行的 message 查：

message	阶段	常见 error 与处理
`config load failed`	读取配置	见配置错误对照
`create data dir failed` / `create uploads dir failed`	创建 `data/`	`permission denied`：运行用户对部署目录没有写权限。Linux `chown -R apexpm:apexpm 部署目录`；macOS 不要放在受保护目录
`database connect failed`	连接数据库	见连接错误对照。SQLite 下多为 `data/` 无写权限或磁盘已满
`migrations failed` / `automigrate failed`	数据库结构升级	保留日志联系我方，不要反复重启。升级后出现的按回滚恢复
`seed failed`	初始化管理员账号	多为数据库权限不足，检查连接用户的写权限
`container init failed`	初始化各模块	正常交付包不应出现，保留完整日志联系我方
`server exited`	监听端口	`address already in use` / `Only one usage of each socket address`：端口被占用。见下文

端口被占用

bash

sudo ss -lntp | grep :9000                 # Linux
lsof -iTCP:9000 -sTCP:LISTEN               # macOS
netstat -ano | findstr :9000               # Windows，最后一列是 PID

多数情况是同一台机器上已经跑着一个 apexpm（比如 systemd 和 start.sh 同时用了）。停掉多余的那个，或修改 server.port。

能启动但访问不了

现象	原因	处理
服务器本机 `curl 127.0.0.1:9000` 正常，其他电脑访问超时	防火墙 / 云安全组没放行	各平台放行方法见部署页；云服务器检查安全组
访问提示「连接被拒绝」	端口不对，或进程没在运行	核对 `server.port`，检查进程状态
页面空白或 404	访问的路径不对，或反向代理配置错	直接访问 `http://IP:9000/` 排除代理问题
能打开登录页，登录报错	看浏览器开发者工具里接口返回的信息；授权被停用时登录后的接口都会失败	先查授权状态
扫码签名打开的地址错误	没配 `server.public_base_url`	按配置说明填写对外地址

授权问题

浏览器提示「系统暂时无法访问」时，先看授权状态：

bash

curl -fsS http://127.0.0.1:9000/api/v1/license/status

reason	原因	处理
`License 文件缺失`	找不到 `data/license.lic`	确认路径与 `license.path` 一致；工作目录是否为部署目录；Docker 确认 `./data` 挂载
`License 无效或被篡改`	签名校验失败	文件传输损坏，重新获取
`IP 未授权`	服务器网卡 IP 不在授权范围	换过服务器 / IP、Docker 用了 bridge 网络、授权时给的是云公网 IP。取网卡真实 IP 联系我方
`License 已过期`	过期	`grace` 为宽限期内，`blocked` 为已停用，联系我方续期

授权详细说明见授权续期。

数据相关

现象	原因	处理
启动正常，但数据全空、只能用 `admin/admin123` 登录	工作目录不对，程序在别处新建了一个空库；或 `config.yaml` 没被读到，数据库配置回落到默认 SQLite	检查服务管理器的工作目录配置；确认 `config.yaml` 在部署目录下
上传附件失败	`data/uploads/` 无写权限，或磁盘已满；走反向代理时可能是请求体大小限制	`df -h` 检查磁盘；调大代理的 `client_max_body_size`
`database is locked`（SQLite）	有其他进程（如备份脚本、另一个 apexpm 实例）在写同一个库	确认只有一个实例在运行；备份改用 `sqlite3 .backup`
忘记 `admin` 密码	—	联系我方协助重置
在线文档打不开，日志有 `在线文档功能禁用` 的 warning	`onlyoffice` 配置不完整或 OSS 凭证错误，程序会跳过该功能继续启动	按 warning 里的 error 修正 `onlyoffice` 段后重启

联系我方时请提供

部署平台与方式（如 Linux systemd、Windows WinSW）
版本号（/health 返回的 version）
/api/v1/license/status 的完整输出
出错前后 100 行日志
最近做过的操作（升级、改配置、换 IP 等）

故障排查总表 ​

排查顺序 ​

启动失败 ​

端口被占用 ​

能启动但访问不了 ​

授权问题 ​

数据相关 ​

联系我方时请提供 ​