Skip to content

AI 英语学习助手实战(四):数据层取舍与部署密钥治理 ​

最后一篇讲两块容易被忽略、但决定项目能不能长期用下去的部分:数据层的几个取舍,以及部署与密钥治理。

一、数据层的三个取舍 ​

1.1 表结构 ​

10 张表,绝大部分挂在用户维度下:

translation_cache(翻译缓存)和 word_details(AI 补全的单词详情)是两张与用户无关的公共表 —— 同一个词对所有用户都一样,没必要按用户各存一份。

1.2 导入词书:upsert,但绝不碰学习进度 ​

教材词书导入是 v2.0.0 的主功能(人教版 9 册共 2842 词)。这里的核心问题是:词表格式升级后要能重新导入,但不能把用户的星级和复习记录冲掉。

sql
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_KEYAI 对话助手「小语」
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 忽略,不进版本库。

本文阅读--次|全站访问--次|访客--人