注意事项与 FAQ
生成的项目可以直接开发，但上线前有几件事必须处理。本页汇总关键注意事项与常见问题。
生产检查清单
Section titled “生产检查清单”- 修改默认密码：
admin仍使用123456，必须立即修改。 - 设置强随机
JWT_SECRET_KEY（Python 后端），不要使用默认值或弱值。 - 不要把
backend/.env提交到版本库：.gitignore已排除.env，请保持。 - 删除或禁用示例用户（
zhangsan、lisi、wangwu、zhaoliu）。 - 收紧 CORS：
CORS_ORIGINS/app.cors-origins只保留真实前端域名。 - 启用 HTTPS：在 Nginx 前再加一层 TLS 终止或使用反向代理。
- 规划双重备份：定期快照 Docker 数据卷，并使用数据管理导出可校验的加密业务包。
弱密钥会拒绝启动
Section titled “弱密钥会拒绝启动”Python 后端启动时校验 JWT_SECRET_KEY：为空或属于弱值集合（secret、123456、changeme、your-secret-key 等）会直接报错退出；长度不足 32 会警告。
openssl rand -base64 48本地开发密钥是临时的
Section titled “本地开发密钥是临时的”若未配置密钥，dev.sh 每次启动都会生成新的随机密钥，因此重启后之前登录的会话会失效，需要重新登录。这只是本地开发现象。
速率限制是单实例内存态
Section titled “速率限制是单实例内存态”登录/注册的速率限制（每分钟 5 次/IP）保存在进程内存中。多实例部署时各实例独立计数，如需全局限制应在网关层实现。
SSRF 防护
Section titled “SSRF 防护”AI 模型连接测试默认拒绝访问本机、内网与云元数据地址，避免被用作内网探测入口。请勿移除该校验。
审计日志含敏感信息
Section titled “审计日志含敏感信息”审计日志记录操作人、IP 与详情，属于合规数据，请控制访问权限并规划保留周期。
完整导出包是高敏感文件
Section titled “完整导出包是高敏感文件”导出包包含密码哈希、AI API Key、SMTP 密码和全部业务数据。导出密码只显示一次且不落库，遗失后无法恢复；文件应立即转移到受控存储，不要留在服务器临时目录或通过非受控渠道分发。
导入会冻结系统并使所有会话失效
Section titled “导入会冻结系统并使所有会话失效”导入期间除一次性任务状态接口外，普通请求返回 503。事务提交成功后全局会话世代会更新，所有用户必须重新登录。应在维护窗口操作，并确保磁盘空间至少能同时容纳数据库、临时快照、上传包和导出包。
| 现象 | 原因与处理 |
|---|---|
| 重启后需要重新登录 | 本地未固定 JWT_SECRET_KEY，见上文 |
| 换后端后令牌失效 | Python 的 JWT 与 Java 的 Sa-Token 令牌不通用 |
| 注册后无法登录 | 开启了人工审核，账号处于 pending_review，需管理员分配角色 |
| 非管理员登录被拒 | 开启了维护模式，管理员仍可登录以关闭它 |
| 无法保存 SMTP 密码 | 含 * 的值会被拒绝（防掩码覆盖），清空请提交空字符串 |
使用 docker compose down -v 后数据消失 |
该命令会删除数据卷，属预期行为 |
| 仪表盘收入/活跃是固定值 | 仪表盘部分字段为示例数据，详见仪表盘 |
| 创建非默认角色用户失败 | 需要额外拥有 users.assign_role 权限 |
| 修改权限码后未生效 | 重启后端触发同步，或调用 POST /api/permissions/sync |
| 自定义菜单点击后 404 | 菜单路由允许自由填写，但仍需在代码中注册对应页面 |
| 内置菜单或分组无法删除 | 内置项的 is_system=true，只能调整顺序和分组 |
| 菜单保存提示版本冲突 | 其他管理员已修改布局，刷新菜单管理后重新调整 |
| 导出后关闭弹窗找不到密码 | 密码只显示一次，必须重新导出 |
| 导入包无法恢复 | 仅支持同后端、同应用版本和同数据结构版本 |
| 导入时接口返回 503 | 系统正在执行全库导入；仅状态接口可通过 jobToken 查询 |
| 导入后所有账号退出登录 | 成功导入会轮换 session_epoch，这是预期行为 |
如何修改注册后的默认角色？
当前注册逻辑按人工审核开关决定为 user 或 pending_review，defaultRoleId 作为配置保留但暂未参与该逻辑。修改角色请通过用户管理，或在后端注册逻辑中调整。
Java 版为什么没有 Swagger？
Java 模板未集成 OpenAPI 文档，接口以 controller/ 下的注解为准。Python 版访问 http://localhost:8088/docs 即可。
前端为什么不用 axios？
约定使用原生 fetch 封装（api/client.ts），便于统一处理 401 与响应结构。Vue 模板的 package.json 中仍列出了 axios，但代码未使用，可以安全移除。
手机能访问后台吗？ 后台界面面向电脑与平板设计，手机访问会显示「请更换设备」的提示，这是模板的预期行为。
数据存在哪里？
开发时是后端目录下的 SQLite 文件；Docker 中位于容器的 /app/data，由命名卷 app-data 持久化。
数据管理是否等于服务端自动备份？
不是。当前只提供手动导出和导入，没有定时备份、历史副本列表、增量恢复或跨版本迁移。服务端级灾难恢复仍需对 app-data 卷做外部快照。
为什么不能把 Python 导出的数据导入 Java？ 导出包包含后端类型和结构版本；当前实现只承诺同版本恢复，不处理两种 ORM、时间类型和迁移历史的跨实现转换。