常见问题 FAQ

部署与运维高频问题排查。

1. 启动类

Q: java -jar 后立即退出？

• 查看控制台/日志首个异常。常见：端口占用（lsof -i:8081）、数据库连不上、Redis 连不上、web.prefix 配置错误。

Q: 提示 Failed to configure a DataSource？

• spring.datasource.url/username/password 配置错误或 MySQL 未启动。确认外置 config 已生效（--spring.config.location 指向对）。

Q: isInstall 返回 code=100？

• Redis 连不上。检查 spring.redis.host/port，redis-cli ping 应返回 PONG。

2. 数据库/编码

Q: 中文乱码？

• 库/表/连接串都要 utf8mb4：新建库加 DEFAULT CHARACTER SET utf8mb4；连接串加 characterEncoding=UTF-8；已有库执行表转码（管理端或 ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4）。

Q: 升级后报"列不存在"（如 price/saleStatus）？

• 未执行表结构升级。去管理端「刷新数据表」（触发 proInstall 自动补列），或按《05》手工 ALTER。

3. 网络/代理

Q: 接口 502？

• Nginx 连不上后端：curl 127.0.0.1:8081 测试；确认 proxy_pass 地址与端口。

Q: 上传超过 20MB 报错？

• 同步调大 nginx client_max_body_size 与后端 spring.servlet.multipart.max-file-size / max-request-size。

Q: 登录后接口 401/未登录？

• 检查 token 传递（参数 token）；确认 Redis 会话未被清空（securityService/缓存清理误删 userInfo）。

4. IP 归属地

Q: 用户 IP 属地（local）为空？

• 确认 jar 旁存在 ip2region_v4.xdb / ip2region_v6.xdb（后端从 jar 父目录加载，不读 classpath）。缺失时将提示并返回空。

5. 微信/支付

Q: 微信通知不生效？

• 检查 RuleApiVisible「公众号配置」与 wechatTemplateId；模板 ID 需与公众号后台一致。

Q: 支付宝回调收不到？

• 回调地址需公网可达且与配置一致；检查网关地址（沙箱/正式 gateway_url）。

6. 其他

Q: 前端页面样式错乱/黑夜下白块？

• 公共 CSS 未更新到最新（static/base.css）；清浏览器缓存或强制刷新。

Q: 文档站（docs）如何部署？

• 整个 docs/ 目录复制到 Web 根（需要 PHP），index.php 即首页；无需数据库。若部署纯静态可省略 PHP（仅教程渲染需要 PHP）。

Q: 端口被占用如何改？

• 改外置 application.properties 的 server.port，并同步 nginx proxy_pass 与 ruleapi.config 的 HEALTH_URL。