Initial commit: WordLoop 单词学习应用

Vue 前端 + FastAPI 后端，含部署脚本与词典数据。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-04 14:30:53 -07:00
commit bd7635986a
66 changed files with 5495 additions and 0 deletions
@@ -0,0 +1,124 @@
+# WordLoop 部署到 Cloudflare · w.tkmind.cn
+
+本指南把 **WordLoop** 通过 **Cloudflare** 暴露为 `https://w.tkmind.cn`。应用为 Vue 前端 + FastAPI 后端 + MySQL，推荐 **Cloudflare Tunnel**（无需公网 IP、自动 HTTPS）。
+
+---
+
+## 一、注册 Cloudflare 并接入域名
+
+1. 打开 [https://dash.cloudflare.com/sign-up](https://dash.cloudflare.com/sign-up) 注册账号（免费计划即可）。
+2. **添加站点** → 输入根域名 **`tkmind.cn`**（子域 `w` 在根域下配置即可）。
+3. Cloudflare 会给出两条 **NS 记录**，到 **购买/解析 tkmind.cn 的注册商**（阿里云、腾讯云、GoDaddy 等）把域名的 DNS 服务器改为 Cloudflare 提供的 NS。
+4. 等待状态变为 **Active**（通常几分钟到 48 小时）。
+
+> 若 `tkmind.cn` 已在 Cloudflare，跳过 2–3，直接进入第二节。
+
+---
+
+## 二、两种接入方式（二选一）
+
+### 方式 A：Cloudflare Tunnel（推荐）
+
+适合：家庭宽带、无固定公网 IP、或不想开放 80/443 端口。
+
+| 步骤 | 操作 |
+|------|------|
+| 1 | 在**运行 WordLoop 的机器**安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) |
+| 2 | `cloudflared tunnel login`（浏览器授权） |
+| 3 | `cloudflared tunnel create wordloop` |
+| 4 | 复制 `deploy/cloudflared/config.yml.example` → `config.yml`，填入 `credentials-file` 实际路径 |
+| 5 | `cloudflared tunnel route dns wordloop w.tkmind.cn` |
+| 6 | 本机 Nginx 按 `deploy/nginx.conf` 监听 `127.0.0.1:8080`，Tunnel 指向该地址 |
+| 7 | `cloudflared tunnel --config deploy/cloudflared/config.yml run` 测试；稳定后用 `deploy/systemd/cloudflared-wordloop.service` |
+
+**DNS 结果**：`w.tkmind.cn` → CNAME → `xxxx.cfargotunnel.com`（由 `tunnel route dns` 自动创建）。
+
+### 方式 B：DNS 代理到自有服务器
+
+适合：已有云服务器与公网 IP。
+
+在 Cloudflare **DNS** → **记录** 添加：
+
+| 类型 | 名称 | 内容 | 代理 |
+|------|------|------|------|
+| `A` | `w` | 服务器公网 IP | 已代理（橙色云） |
+
+服务器上：Nginx（`deploy/nginx.conf`）+ 后端 systemd（`deploy/systemd/wordloop-backend.service`），**SSL 由 Cloudflare 边缘终止**（源站可只开 80 或由 Tunnel/内网访问）。
+
+**SSL/TLS** 建议：**完全（严格）** 需在源站配置证书；起步可用 **灵活**（仅访客到 Cloudflare 为 HTTPS）。
+
+---
+
+## 三、服务器部署清单
+
+```bash
+# 1. 同步代码到例如 /var/www/wordloop
+# 2. 后端
+cd /var/www/wordloop/backend
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env   # 生产务必修改 MYSQL_* 与 WORDLOOP_SECRET_KEY
+
+# 3. MySQL 建库（与 README 一致）
+mysql -h ... -u ... -p -e "CREATE DATABASE IF NOT EXISTS wordloop ..."
+
+# 4. 构建前端
+cd /var/www/wordloop && chmod +x deploy/build.sh && ./deploy/build.sh
+
+# 5. Nginx
+sudo cp deploy/nginx.conf /etc/nginx/sites-available/wordloop
+# 修改 root 路径为实际 dist 目录
+sudo ln -sf /etc/nginx/sites-available/wordloop /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+
+# 6. 后端服务
+sudo cp deploy/systemd/wordloop-backend.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now wordloop-backend
+```
+
+---
+
+## 四、生产环境变量
+
+`backend/.env` 示例：
+
+```env
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=wordloop
+MYSQL_PASSWORD=<强密码>
+MYSQL_DATABASE=wordloop
+WORDLOOP_SECRET_KEY=<随机长字符串>
+```
+
+前端生产构建使用相对路径 `/api`，与 `deploy/nginx.conf` 反代一致，**无需改前端代码**。
+
+---
+
+## 五、验证
+
+1. `curl -I https://w.tkmind.cn` 应返回 200。
+2. 打开 `https://w.tkmind.cn` 能注册/登录。
+3. API：`https://w.tkmind.cn/api/`（或通过页面功能间接验证）。
+4. 可选：`https://w.tkmind.cn/docs`（FastAPI 文档，生产可关）。
+
+---
+
+## 六、常见问题
+
+| 现象 | 处理 |
+|------|------|
+| DNS 未生效 | 确认 NS 已指向 Cloudflare；`dig w.tkmind.cn` |
+| 522 / 连接失败 | Tunnel 未运行或 Nginx/后端未监听 8080 / 18004 |
+| API 401 / CORS | 同源访问应走 `/api`；勿把 API 指到另一域名 |
+| 仅子域在 CF | 也可只把 `w` 用 CNAME 到 Tunnel，根域 NS 可仍在原注册商（需支持 CNAME 到 cfargotunnel.com） |
+
+---
+
+## 本仓库相关文件
+
+- `deploy/nginx.conf` — 静态站 + `/api` 反代
+- `deploy/cloudflared/config.yml.example` — Tunnel 配置模板
+- `deploy/systemd/*.service` — 后端与 Tunnel 开机自启
+- `deploy/build.sh` — 前端生产构建