AI 英语学习助手实战(四):数据层取舍与部署密钥治理
最后一篇讲两块容易被忽略、但决定项目能不能长期用下去的部分:数据层的几个取舍,以及部署与密钥治理。
一、数据层的三个取舍
1.1 表结构
10 张表,绝大部分挂在用户维度下:
translation_cache(翻译缓存)和 word_details(AI 补全的单词详情)是两张与用户无关的公共表 —— 同一个词对所有用户都一样,没必要按用户各存一份。
1.2 导入词书:upsert,但绝不碰学习进度
教材词书导入是 v2.0.0 的主功能(人教版 9 册共 2842 词)。这里的核心问题是:词表格式升级后要能重新导入,但不能把用户的星级和复习记录冲掉。
INSERT INTO wordbook (user_id, english_word, chinese_meaning, ...)
VALUES (?, ?, ?, ...)
ON CONFLICT(user_id, english_word) DO UPDATE SET
chinese_meaning = excluded.chinese_meaning,
pronunciation = excluded.pronunciation,
part_of_speech = excluded.part_of_speech,
example_sentence = excluded.example_sentence,
example_translation = excluded.example_translation,
more_examples = excluded.more_examples,
updated_at = CURRENT_TIMESTAMP
-- 注意:DO UPDATE 里没有 mastery_level / review_count / last_reviewed / source💡 经验:"不写什么"比"写什么"更重要 —— 这四个字段故意不出现在
DO UPDATE子句里,于是重导词表天然不会影响已有进度,也不需要额外写"先查再判断再决定更新哪些列"的逻辑。导入因此是幂等的,重复点也不会产生重复词。
1.3 成就判定:定义与记录分离
achievements 表只记录"什么时候拿到的",靠 UNIQUE(user_id, achievement_type) 兜底,同一成就不会重复授予。而"怎么算达成"集中在 app.py 的 ACHIEVEMENT_DEFS 里,12 个成就一张定义表。
判定不是埋点驱动,而是打开成长页时按当前数据算一遍。好处是加新成就只加一行定义;代价是每次打开页面要跑一遍判定 —— 在这个数据量下完全可以接受。
1.4 统计口径:在学 vs 全部
单词本顶部的册次筛选有个容易搞错的细节:下拉框里的数字是还在学的词数(mastery_level < 3),不是该册总词数。因为 3 星的词已经移进成长页的「我的单词」,不该再占着筛选数字。
接口因此同时返回两个数:count(在学)和 total(全部)。另外给了一个 stats_only=1 参数 —— 学成一个词后只需要刷新下拉里那个数字,为它去拉全量词表不值得,这个参数只返回统计,响应体约 250 字节。
二、部署与密钥治理
2.1 一条命令起服务
本地是 start.bat / start.sh,内部做四件事:检查 Python 版本 → 安装依赖 → 初始化数据库 → 加载 .env 并启动,最后打开浏览器。
线上用 Docker Compose,前面挂 nginx。数据库文件通过卷挂载到宿主机 ./database/,删容器不丢数据;容器内以 FLASK_DEBUG=false 运行,避免 Werkzeug 调试器暴露。
2.2 密钥全部移出代码
这是专门做过的一次清理:所有 API 密钥统一进项目根目录的 .env,仓库里只保留不含密钥的 .env.example 模板。
| 变量 | 用途 |
|---|---|
DEEPSEEK_API_KEY | AI 对话助手「小语」 |
YOUDAO_APPKEY / YOUDAO_SECRET | 有道翻译 |
BAIDU_APPID / BAIDU_SECRET | 百度翻译 |
BAIDU_SPEECH_APP_ID / ..._API_KEY / ..._SECRET_KEY | 百度语音识别 |
BAIDU_OCR_API_KEY / BAIDU_OCR_SECRET_KEY | 百度 OCR |
PIXABAY_API_KEY | 单词记忆图片 |
只填需要的即可,留空的功能自动降级。非敏感参数(模型名、max_tokens、temperature)单独放在 deepseek_config.json,和密钥分开 —— 这个文件可以安全提交,换模型不用动环境变量。
2.3 容器化的三个坑
- 目录大小写:仓库里是
Backend/、Frontend/,容器内是/app/backend、/app/frontend。应用层做了不区分大小写的路径解析,所以两种写法都能跑 - 时区:容器默认 UTC,和宿主机差几个小时。连续学习天数、本月掌握这类按日期统计的功能,时区错了会直接算错
- 静态资源解析:目录挂载方式会影响静态文件路径,需要按文件/目录精确挂载,而不是整目录挂载
本地开发用 docker-compose.override.yml 把 Frontend/、Backend/ 挂进容器:改前端刷新即可,改后端只需 docker compose restart。这个文件被 .gitignore 忽略,不进版本库。