维护、更新与常见问题

OpenCareer 是一个需要长期维护的本地工作区。维护重点不是频繁改数据库，而是保持框架代码、个人数据、附件和备份之间的边界清晰。

同步外部修改的文件

如果你使用 Word、WPS 或其他本地软件修改了附件的文件名、路径或内容，可以在界面中打开：

设置 → 同步文件

也可以运行：

python opencareer/app.py --data-dir .career-data files sync

同步用于刷新文件名、路径、哈希和修改时间。它不会替你改变岗位或投递记录。

导出与备份

在重要调整前，先创建数据库备份；需要审阅或恢复时，再生成 JSON 快照。备份整个 .career-data/ 可以同时保留数据库和附件。

建议至少保留：

• 当前工作区；
• 最近一次可用备份；
• 一份与项目代码分离的离线备份。

页面是示例数据或只读模式

如果页面打开后显示示例候选人，或者按钮全部是只读状态，通常是因为直接打开了静态 opencareer/web/index.html。请改用：

start-opencareer.cmd

或者：

python opencareer/app.py serve

正式页面需要本地服务提供数据读写和 Agent 接口。

8721 端口被占用

启动脚本会检查端口。如果 8721 已被使用，可以选择打开已有服务，或为当前工作区选择新的可用端口。后续访问 /api、/mcp 和 /api/docs 时，都要使用终端实际显示的端口。

更新没有版本号怎么办

OpenCareer 是纯代码项目，没有强制的发布版本号。更新时使用：

git pull

本教程页会把 GitHub 最近一次提交日期作为代码快照标识，并链接到对应提交。它表示“仓库最近何时发生变化”，不是语义化版本号；要判断是否适合当前工作区，仍应阅读提交说明和项目变更。

怀疑数据库或附件异常

先停止正在运行的服务，复制整个 .career-data/ 作为保护性备份，再运行：

python opencareer/app.py --data-dir .career-data doctor

如果问题涉及某个附件，优先检查它在 files/ 中是否仍然存在，以及是否刚刚被外部软件移动或改名。