常见问题
先根据报错所在的位置选择下面的入口。排查时保留当前配置和数据，记录完整异常中的 Caused by；最后一行“启动失败”往往只是结果。
| 在哪里出错 | 优先查看 |
|---|---|
| Docker 容器未启动 | 端口冲突、容器日志 |
| Java 编译失败 | JDK 和 Maven |
| Java 启动失败 | 连接与配置、Flyway |
| 页面能打开但不能用 | 前端代理、Cookie、权限 |
查看开发容器与日志
在后端根目录执行以下只读命令：
# 开发项目的状态
docker compose --env-file /dev/null -p art-design-pro-x-java-dev -f docker-compose.yml -f deploy/compose.dev.yml ps -a
# 最近的数据服务日志
docker compose --env-file /dev/null -p art-design-pro-x-java-dev -f docker-compose.yml -f deploy/compose.dev.yml logs --tail=100 mysql redis开发模式没有运行 Java 容器，后端错误看 IDE 控制台或 node scripts/dev.mjs 的终端，脚本日志也在 logs/art-design-pro-x-java.log。sh scripts/deploy.sh status 用于生产项目；不要据此判断开发服务是否存在。
JDK 或 Maven 编译失败
在后端根目录运行 java -version 与 ./mvnw -version，确认均为 JDK 21。IDE SDK、Maven 导入和运行配置也需一致。首次联网下载依赖失败先排查仓库访问，不修改产品依赖版本碰运气。
Docker Healthy，但 Java 数据库连接失败
Docker 健康不等于应用账号和配置正确。核对 Java 是否加载根目录 config/application-dev.yml、工作目录和 spring.config.additional-location；比较脱敏后的主机与端口，不打印完整密码。
随包 Redis 本机端口为 16379，自装通常为 6379；不要将 Docker 内的 mysql/redis 服务名直接用于宿主机 Java。
常见连接错误分别代表什么
| 日志关键字 | 优先处理 |
|---|---|
Connection refused / Communications link failure | 服务是否运行、主机/端口是否正确、网络是否可达 |
Access denied for user | 实际加载的账号、密码及数据库授权；容器 Healthy 不能证明这些正确 |
Unknown database | 库名和已有服务中是否建库；自备服务首次需要空数据库 |
NOAUTH / WRONGPASS | Redis 实际密码是否与 YAML 一致 |
Public Key Retrieval is not allowed | 先核对是否加载了正确外置 JDBC URL，再根据 MySQL 认证与 TLS 方案处理；生产不要直接照搬关闭 TLS 的开发参数 |
已有数据卷的 MySQL 账号密码不会随 YAML 重新生成。恢复匹配的原配置，或按数据库维护流程轮换密码，再重启应用。
端口被占用
如果 Docker 提示 127.0.0.1:3306: bind: address already in use，表示本机 3306 已有进程监听，MySQL 容器尚未成功绑定端口。与 Java 版本、数据库表和图片上传无关。
推荐保留已有服务，为本项目换一个空闲端口：
- 在后端根目录执行
sh scripts/deploy.sh init-dev，准备开发配置。 - 编辑
config/application-dev.yml，只把 JDBC URL 中的127.0.0.1:3306改为127.0.0.1:13306，保留库名、URL 参数和密码。 - 执行
sh scripts/deploy.sh dev，脚本同步生成端口映射。 - 重启本机 Java，确认健康检查通过。
macOS/Linux 可用 lsof -nP -iTCP:3306 -sTCP:LISTEN 查看占用者。Redis 冲突则修改同一 YAML 的 spring.data.redis.port 后重跑 dev。删除数据卷不会解决端口占用。
若是 Java 的 13001 被占用，先确认没有 IDE 与脚本重复启动。确需换端口时按 应用配置 修改 server.port，同步前端代理。
前端打开，但请求 404
Java 默认 13001，Nest.js 默认 13000，.env.development 仅启用一个代理目标，修改后重启前端。生产不使用 Vite 开发代理，需要网关转发。
接口版本以实际封装为准，菜单当前是 /api/v3/system/menus，不能把所有接口替换为 /api/v1。
登录成功后刷新退出
检查 Refresh Cookie 的写入、Secure、SameSite、域名和代理转发。Java 本地 HTTP 使用开发配置，公网 HTTPS 保持 Secure。跨站 Cookie 受浏览器策略约束，允许 CORS 不等于 Cookie 一定发送。
请求没有签名头
Java 当前公开配置 signatureRequired: false，共享前端会跳过签名，这是预期。Bearer 登录态与 API 权限仍需校验，不能通过前端手动补头替代服务端配置。
菜单或接口 403
核对有效角色、菜单按钮、接口显式授权与数据范围。自定义角色还需当前用户、退出、个人资料与会话等基础 account 权限。用普通账号复现，不仅测试超级管理员。
Flyway 校验失败或非空库拒绝
核对运行版本、迁移目录与 flyway_schema_history。首次安装用空库；已有客户库按前向迁移升级。不删除历史记录、不修改已执行 SQL，也不直接用 repair 掩盖结构差异。详见 数据库初始化。
修改公共模块后仍然是旧行为
单独运行 art-admin 可能读到本机 Maven 仓库的旧依赖。停止本地后端后重新执行 node scripts/dev.mjs 构建安装再启动。仅执行 test/verify 不会更新本机已安装模块。
AI、MinIO 或审批看起来不完整
- AI 503：核对模型配置；Java 不包含 AI 代码生成器。
- MinIO 无标签/筛选：前端尚需 MINIO 类型与展示适配，不代表对象一定上传失败。
- 审批没有可选组织：交付库不创建演示组织，配置实际部门和人员。
- 商城无法写初始库存：先建立启用的默认仓库和基础资料。
支付超时或退款未确认
保留原流水，先查询渠道和回调，不能直接标记失败、人工覆盖或重建支付。HTTP 错误和网络超时不证明渠道未受理。见 支付接入。
给支持人员或 AI 提供什么
应用版本、运行方式、接口方法/路径、HTTP 与业务码、最小复现、相关时间、脱敏日志及已核对的配置属性。去除密码、Token、私钥、临时链接与商户凭据。将问题定位到配置、认证、权限、SQL、文件或外部服务，再提出具体变更。
JAR 初始化提示找不到 example 文件
java -jar art-admin.jar --init-config=prod 从当前目录读取 config/application-prod.example.yml。仅复制 JAR 不够，还需带上仓库的对应模板，目录结构见 JAR 交付。已有实际配置时保留原文件，不重新生成凭据。