2.6 KiB
2.8 常见问题 FAQ
:::tip 概述 本页汇总快速入门阶段的高频问题。更多排错手段见 11.10 故障排查手册。 :::
启动类
Q：启动即退出，提示配置校验失败？
启动是 fail-fast 的：JWT 密钥为空或过短、DSN 字段不完整都会直接退出。按提示修正 config.yaml 或对应 APP_* 环境变量。生产模式（app.prod=true）还会拒绝默认密钥、万能验证码与未关闭的生成器。
Q：提示 Redis 连接失败？
Redis 是可选依赖。cache.Init 探测失败会自动降级内存模式并打告警日志，服务照常启动。需要真实 Redis 时核对 redis.default.address/pass。
Q：Windows 下 make 命令不可用？
使用 make.bat <目标>，两套目标完全一致。
Q：8000 端口被占用？
改 server.address（如 :8001），或释放占用端口。注意同步改前端代理目标。
数据库类
Q：连接被拒绝 / 访问被拒绝？
确认 MySQL 已启动、账号密码与 database.default 一致、库已创建并导入种子脚本。
Q：想换 PostgreSQL / SQL Server 怎么办？
改 database.default.driver 与连接字段即可，代码零改动。已有数据用 make migrator 跨库搬迁，见 7.6 数据库迁移工具。
Q：物理删除报错被拦截？
这是设计行为——一切删除走软删除（del_flag=1），物理删除被全局钩子拦截。定时清理等特殊场景用 WithPhysicalDelete(ctx) 显式放行。
前端类
Q：pnpm dev 后页面接口全部 404/代理失败？
后端未启动或端口不一致。确认 /api/health 可访问，并核对 ui/.env.development 的 VITE_PROXY 指向。
Q：登录提示验证码错误？
验证码有 300 秒有效期且一次性。开发调试可配置 captcha.bypassCode 万能码——但生产模式下非空万能码会被拒绝启动。
配置类
Q：新增了配置键，make check-config 报不一致？
新增键必须同步写入 .env.example。这是硬检查项，两者键集合必须一致。
Q：环境变量设置了但不生效？
覆盖规则：键名 = 配置路径大写、点换下划线、加 APP_ 前缀；且仅覆盖 YAML 中已存在的键，空值视为未设置。例：database.default.host → APP_DATABASE_DEFAULT_HOST。
Q：上传的文件访问不到？
生产环境由 Nginx 直供 upload 目录，file.domainUrl 配置访问基址（不含 upload 段）。本地未配置域名时应用挂开发回退且封禁 temp 目录。详见 7.2 上传配置详解。