doc-migration-guide

迁移路径说明如下： **变更内容：** 本次更新对系统核心模块进行了重构，包括数据库结构优化、API 接口版本升级以及部分配置项的废弃。主要变更包括： - 数据库表 `users` 中字段 `username` 更名为 `login_name`，并新增唯一索引。 - API 接口从 v1 升级至 v2，部分请求参数和响应结构发生变化。 - 配置文件中的 `legacy_auth` 选项已废弃，统一使用新的认证机制。 **受影响方：** - 所有使用旧版 API（v1）的第三方应用或前端服务。 - 依赖 `username` 字段进行数据查询或同步的内部系统。 - 仍在使用 `legacy_auth` 配置项的部署环境。 **安全升级步骤：** 1. **备份数据：** 在升级前，请完整备份数据库及当前配置文件。 2. **测试环境验证：** 在非生产环境中部署新版本，验证所有依赖功能是否正常。 3. **逐步迁移数据库：** - 执行数据库迁移脚本，将 `username` 字段重命名为 `login_name`。 - 确保迁移过程中无数据丢失，并验证索引创建成功。 4. **更新应用代码：** - 将调用旧版 API（v1）的代码替换为 v2 接口，并适配新的参数与响应格式。 - 移除对 `username` 字段的直接引用，改为使用 `login_name`。 5. **切换认证机制：** - 更新配置文件，移除 `legacy_auth` 配置项，启用新的认证方式。 - 验证用户登录与权限控制功能正常。 6. **灰度发布：** 先对部分用户或流量进行新版本发布，监控系统稳定性与错误日志。 7. **全面上线：** 确认无异常后，完成全量部署，并通知相关方更新文档与接入指南。 **注意事项：** - 升级过程中请确保服务高可用，避免长时间停机。 - 如遇问题，可使用备份快速回滚至旧版本。 - 建议在低峰时段执行数据库变更操作。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本