# 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` — 前端生产构建