noteTb: 300
This data as json
| id | user_id | content | tags | created_at | updated_at | enable | pinned | folder_id | comment | position | visibility |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 300 | 1 1 | # 英文单词查询学习助手 — 项目手册 作者：Manus 版本：1.0 ## 项目概览 | 项目 | 值 | |------|-----| | 名称 | 英文单词查询学习助手 | | 线上地址 | https://leedreamer.cn/english | | 服务器 | 阿里云 leedreamer.cn（8.219.6.216） | | 服务目录 | /home/project/EnglishWord | | systemd 服务 | english-word | | 监听端口 | 3001 | | 源码仓库 | Manus webdev 项目 word_query_app | --- ## 技术栈 | 层 | 技术 | |----|------| | 前端 | React 19 + Tailwind 4 + shadcn/ui | | 后端 | Express 4 + tRPC 11 | | 数据存储 | Excel（xlsx）文件，每个用户一个 sheet | | 字典 | StarDict SQLite（dictionary.db，约 70MB） | | LLM | DeepSeek-V4-Flash（deepseek-v4-flash） | | 构建 | Vite + esbuild | --- ## 数据文件 | 文件 | 路径 | 说明 | |------|------|------| | 单词数据 | /home/project/EnglishWord/data/words.xlsx | 每个用户一个 sheet，__users__ sheet 存用户列表 | | 字典数据库 | /home/project/EnglishWord/data/dictionary.db | StarDict SQLite，只读，70MB | ### words.xlsx 结构 - `__users__` sheet：用户列表，列：username - 每个用户 sheet（如 `leedreamer`）：列 word、meaning、phonetic、queryCount、examples（JSON）、createdAt、updatedAt --- ## 服务管理 ```bash # 查看状态 systemctl status english-word # 重启 systemctl restart english-word # 查看日志 journalctl -u english-word -n 50 --no-pager ``` --- ## 部署流程 1. 在 Manus 沙盒中修改源码（/home/ubuntu/word_query_app） 2. 构建：`pnpm build` 3. 打包：`tar -czf /tmp/english_app.tar.gz dist/` 4. 上传：`scp -i ~/.ssh/id_rsa /tmp/english_app.tar.gz root@leedreamer.cn:/tmp/` 5. 解压：`cd /home/project/EnglishWord && tar -xzf /tmp/english_app.tar.gz` 6. 清理 Manus runtime 脚本（index.html 里的 manus-runtime script 标签） 7. 重启：`systemctl restart english-word` --- ## 环境变量（systemd 服务配置） | 变量 | 说明 | |------|------| | NODE_ENV | production | | PORT | 3001 | | DEEPSEEK_API_KEY | DeepSeek API Key（sk-1685481...） | | DEEPSEEK_BASE_URL | https://api.deepseek.com/v1 | | DEEPSEEK_MODEL | deepseek-v4-flash | --- ## 主要功能 ### 1. 单词查询 - 输入英文单词，实时在输入框上方显示字典解释（灰色小字，300ms 防抖） - 字典来源：本地 dictionary.db（StarDict 格式） - 查询接口：GET /api/dict/search?q=单词 ### 2. 添加单词 - 添加按钮与中文释义输入框同行（节省空间） - 已有单词显示 "+1"（增加查询次数），新词需填写中文释义 - 按 Tab 从单词输入框跳到释义输入框，按 Enter 提交 ### 3. 单词列表 - 按查询次数排序，高频词高亮 - 支持行内编辑中文释义 - 支持删除单词 ### 4. 生成例句 - 调用 DeepSeek-V4-Flash 生成 3 个例句 - 例句有缓存，避免重复调用 LLM - 可点击刷新强制重新生成 ### 5. 多用户 - 每个用户数据独立存储在 words.xlsx 的独立 sheet 中 - 登录页选择用户名（无密码） --- ## API 接口 | 接口 | 说明 | |------|------| | GET /api/dict/search?q=word | 本地字典搜索 | | POST /api/trpc/words.list | 获取用户单词列表 | | POST /api/trpc/words.add | 添加单词 | | POST /api/trpc/words.delete | 删除单词 | | POST /api/trpc/words.updateMeaning | 更新中文释义 | | POST /api/trpc/words.generateExamples | 生成例句（DeepSeek） | | POST /api/trpc/words.refreshExamples | 强制刷新例句 | --- ## 踩坑记录 ### 坑1：生成例句失败（BUILT_IN_FORGE_API_KEY=placeholder） - **现象**：点生成例句无响应或报错 - **原因**：服务器 systemd 环境变量 BUILT_IN_FORGE_API_KEY 是占位符，不是真实 key - **解决**：改用 DeepSeek API 直接调用，在 server/routers.ts 里用 fetch 调 https://api.deepseek.com/v1/chat/completions ### 坑2：better-sqlite3 构建脚本被 pnpm 阻止 - **现象**：pnpm install 后 better-sqlite3 无法加载（native binding 未编译） - **原因**：pnpm 默认阻止 native 模块的构建脚本 - **解决**：在 package.json 的 pnpm.onlyBuiltDependencies 里添加 "better-sqlite3" ### 坑3：DeepSeek 模型名称 - **正确模型 ID**：deepseek-v4-flash（不是 deepseek-v4-flash-chat 等变体） - 通过 GET https://api.deepseek.com/models 确认 ### 坑4：前端 bundle 里有 Manus runtime script - **现象**：部署到自己服务器后，页面加载 Manus 相关脚本报错 - **解决**：部署后用 Python 正则清理 dist/public/index.html 里的 manus-runtime 和 debug-collector.js 标签 --- ## 文件结构（源码） ``` word_query_app/ client/src/pages/Home.tsx ← 主页面（登录选择 + 单词列表 + 字典提示） server/_core/index.ts ← Express 服务入口（含 /api/dict/search 路由） server/routers.ts ← tRPC 路由（单词 CRUD + DeepSeek 例句生成） server/db.ts ← Excel 数据库操作（exceljs） data/words.xlsx ← 单词数据（服务器上） data/dictionary.db ← StarDict 字典（服务器上，不在源码里） ``` | ["英文单词", "项目手册"] | 2026-05-14 12:35:41 | 2026-05-14 12:35:41 | T | F | 18 | public |