ci(deploy): 添加 dev 自动部署脚本

docs/technical-guide.md

@@ -88,6 +88,43 @@ PORT=8080 python3 app.py
 
 使用已安装 `requirements.txt` 的 Python 环境。若 8080 已有本项目实例，先停止旧实例再启动，使 Flask 加载新接口。迁移可重复执行；运行账户需要目标表的读写权限。目标表不参与 `fetch_data.py` 的采集覆盖。
 
+## GitHub 自动部署
+
+服务器部署使用根目录的 `deploy.sh`。脚本会先拉取指定分支，再检测 Python 环境；若项目 `.venv` 不存在，会自动用系统 `python3` 或 `python` 创建 `.venv`，随后安装 `requirements.txt`、执行阅读目标迁移，并重启 systemd 服务。
+
+当前服务器配置可按下列默认值使用：
+
+```sh
+PROJECT_DIR=/opt/weread-board/WeReadBoard
+SERVICE_NAME=weread.service
+VENV_DIR=/opt/weread-board/WeReadBoard/.venv
+```
+
+GitHub Actions 文件位于 `.github/workflows/deploy.yml`，默认在 `dev` 分支 push 后触发，也支持手动触发。仓库需要在 `Settings -> Secrets and variables -> Actions -> Secrets` 配置：
+
+| Secret | 说明 |
+|---|---|
+| `SERVER_HOST` | 服务器 IP |
+| `SERVER_PORT` | SSH 端口，未配置时按 22 处理 |
+| `SERVER_USER` | SSH 登录用户 |
+| `SERVER_SSH_KEY` | GitHub Actions 登录服务器用的私钥 |
+
+可选配置放在 `Settings -> Secrets and variables -> Actions -> Variables`：
+
+| Variable | 说明 |
+|---|---|
+| `DEPLOY_PATH` | 可选，默认 `/opt/weread-board/WeReadBoard` |
+| `SERVICE_NAME` | 可选，默认 `weread.service` |
+
+如果在服务器手动部署，可执行：
+
+```sh
+cd /opt/weread-board/WeReadBoard
+DEPLOY_BRANCH=dev ./deploy.sh
+```
+
+`deploy.sh` 会优先读取项目根目录 `.env`；没有 `.env` 时，会读取 `weread.service` 当前 `Environment=` 配置。按截图中的 service 写法也能拿到端口、API Key 和数据库配置。若以后改用普通部署用户，需要允许该用户免密执行 `systemctl restart weread.service`。
+
 浏览器旧目标不会自动覆盖数据库。在原访问地址打开“阅读目标”，点击“导入已有目标”；数据库已有同一 ID 时跳过，整批成功才标记导入完成。`weread-goals-v2` 原数据保留，`weread-goals-v2-imported` 只记录已导入。不同浏览器、域名和端口的旧存储需要分别在原地址导入。
 
 保存失败会保留表单并提示重试；读取失败显示错误和重试按钮，不冒充空列表。若新建提示 ID 已存在，刷新目标列表确认上次请求是否已经保存。数据库不可用或尚未执行迁移时，目标接口返回 503，不退回浏览器保存。
@@ -105,4 +142,8 @@ node --check static/js/weapi.js
 
 本次样式收紧覆盖正式看板的概览、书架和阅读目标页。顶栏、标题区、筛选区、统计卡、书架网格、右侧目标摘要、目标介绍区和目标卡片均使用覆盖规则压缩占位；书架在窄屏固定两列，避免横向溢出。本地真实数据验收覆盖 1280 px 桌面和 390 px 手机宽度：桌面顶栏 58 px，统计卡从约 200 px 开始，书架一行 7 本，目标页介绍区约 67 px 高，目标卡约 317 px 宽；手机顶栏 56 px，书架两列，目标卡约 298 px 宽，概览、书架和目标页均未出现横向溢出。
 
+## dev 自动部署
+
+`dev` 分支 push 后由 `.github/workflows/deploy.yml` 触发部署。Actions 通过仓库 Secrets 登录服务器，在 `DEPLOY_PATH` 指定的目录先拉取 `origin/dev`，再执行根目录 `deploy.sh`，完成加载可选 `.env`、安装 Python 依赖、执行阅读目标表迁移和重启 systemd 服务。详细配置见 `docs/deploy-dev.md`。
+
 本次数据库验收已在 8080 正式看板完成：页面新建目标后刷新仍可读取，编辑后再次刷新仍可读取，并已清理临时验收目标。读取目标列表未完成时，新建和编辑入口只显示目标页的加载或错误状态，不会打开保存表单。