62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# 2.8 常见问题 FAQ
|
||
|
||
:::tip 概述
|
||
本页汇总快速入门阶段的高频问题。更多排错手段见 [11.10 故障排查手册](/zh/deploy/troubleshooting.html)。
|
||
:::
|
||
|
||
## 启动类
|
||
|
||
**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 数据库迁移工具](/zh/tools/db-migrate.html)。
|
||
|
||
**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 上传配置详解](/zh/tools/upload-config.html)。
|