初始化新时空数据应用

2026-06-12 02:11:47 +08:00
commit aab9da4f31
18 changed files with 3492 additions and 0 deletions
@@ -0,0 +1,102 @@
+# 新时空课程记录查询网页
+
+这是一个只读查询工具，用于把本机正式业务源中的 `classnotes.txt` 和 `学生课时账户.md` 同步到 VPS，并通过网页查询上课记录和课时账户。
+
+## 目录
+
+- `app/`：FastAPI 后端和内置前端页面。
+- `scripts/deploy_to_vps.py`：部署网页服务到 VPS。
+- `scripts/sync_to_vps.py`：同步正式数据文件到 VPS。
+- `scripts/install_launch_agent.py`：安装 Mac 开机常驻同步任务。
+- `launchd/com.xsk.records.sync.plist.template`：LaunchAgent 模板。
+
+## 首次部署
+
+推荐先配置 SSH key。若临时使用密码，可通过环境变量传入，不要写入仓库文件。
+
+```bash
+cd /Users/yangdawei/Desktop/新时空业务源数据/tools/xsk-records-web
+XSK_USE_SSHPASS=1 \
+XSK_SSH_PASSWORD='填写SSH密码' \
+XSK_WEB_PASSWORD='填写网页访问密码' \
+python3 scripts/deploy_to_vps.py --use-sshpass
+```
+
+默认访问地址：
+
+```text
+http://121.199.172.246:18080/
+```
+
+默认网页用户名为 `wolfydw`。网页密码只写入 VPS 的 `/root/新时空数据/app/.env`，不会提交进 Git。
+
+如果 VPS 无法访问 Docker Hub，部署脚本会默认使用 `swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim` 作为基础镜像。需要更换时设置：
+
+```bash
+XSK_PYTHON_IMAGE='python:3.12-slim'
+```
+
+## 手动同步数据
+
+```bash
+XSK_USE_SSHPASS=1 \
+XSK_SSH_PASSWORD='填写SSH密码' \
+python3 scripts/sync_to_vps.py --once --use-sshpass
+```
+
+同步文件：
+
+- `/Users/yangdawei/Desktop/新时空业务源数据/新时空课程记录与课时账户/classnotes.txt`
+- `/Users/yangdawei/Desktop/新时空业务源数据/新时空课程记录与课时账户/学生课时账户.md`
+
+远端数据目录：
+
+```text
+/root/新时空数据/data/
+```
+
+## 安装自动同步
+
+```bash
+XSK_USE_SSHPASS=1 \
+XSK_SSH_PASSWORD='填写SSH密码' \
+python3 scripts/install_launch_agent.py --use-sshpass
+```
+
+日志位置：
+
+```text
+~/Library/Logs/xsk-records-web/sync.log
+~/Library/Logs/xsk-records-web/sync.err.log
+```
+
+查看任务：
+
+```bash
+launchctl list | grep com.xsk.records.sync
+```
+
+卸载任务：
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.xsk.records.sync.plist
+rm ~/Library/LaunchAgents/com.xsk.records.sync.plist
+```
+
+## 更换网页访问密码
+
+登录 VPS 后修改 `/root/新时空数据/app/.env` 中的 `BASIC_AUTH_PASSWORD`，然后重启：
+
+```bash
+cd /root/新时空数据/app
+docker compose up -d
+```
+
+## API
+
+- `GET /api/health`：数据状态。
+- `GET /api/records?q=王鑫鹏5月数学课`：自然语言查询上课记录。
+- `GET /api/accounts`：课时账户列表。
+- `GET /api/accounts?q=王鑫鹏`：按学生筛选账户。
+- `GET /api/accounts?status=欠费`：按账户状态筛选。
+- `GET /api/accounts/王鑫鹏`：单个学生账户。