docs: README 补充一键部署(up)、就绪探测与 Git 推送说明

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -13,6 +13,7 @@
 - [Watchdog 健康监测](#watchdog-健康监测)
 - [macOS 开机自启](#macos-开机自启)
 - [开发模式](#开发模式)
+- [推送代码到 Git 服务器](#推送代码到-git-服务器)
 - [自动化测试](#自动化测试)
 - [项目结构](#项目结构)
 - [常见问题](#常见问题)
@@ -63,11 +64,24 @@ ADMIN_PASSWORD=your_secure_password
 
 ### 3. 构建与启动
 
+推荐一键部署（构建 + 启动 + 健康监测，一步到位）：
+
+```bash
+# 一键部署：build + start + watchdog（强制重来）
+./deploy.sh up
+```
+
+`up` 会自动构建前端、（强制）重启后端并**轮询 `/api/health` 直到就绪**才返回，再拉起 watchdog，最后打印状态。适合首次部署和更新代码后重新上线。
+
+> ⚠️ `up`/`start` 采用「强制重来」语义：若检测到旧服务会先停再起，正在进行的打包任务会被中断。
+
+也可以分步执行：
+
 ```bash
 # 一键构建（安装依赖 + 构建前端）
 ./deploy.sh build
 
-# 启动服务
+# 启动服务（等待就绪；端口被非本项目进程占用时会明确报错）
 ./deploy.sh start
 ```
 
@@ -179,6 +193,9 @@ GIT_PASSWORD=<仅 read_repository 权限的 Personal Access Token>
 |------|--------|------|
 | `WATCHDOG_INTERVAL` | `30` | 健康检查间隔（秒） |
 | `WATCHDOG_TIMEOUT` | `10` | HTTP 健康检查超时（秒） |
+| `WATCHDOG_STARTUP_GRACE` | `10` | 首次检查前的宽限（秒），避开服务正常启动窗口，防止误重启 |
+| `STARTUP_READY_TIMEOUT` | `20` | `start` 后等待 `/api/health` 就绪的最长时间（秒） |
+| `WATCHDOG_RESTART_MODE` | `nohup` | 重启方式：`nohup`（PID 文件托管）或 `launchd`（用 `launchctl kickstart` 交回 launchd 托管，避免与 KeepAlive 抢端口） |
 | `MAX_RESTART_ATTEMPTS` | `3` | 连续重启上限，超过后进入冷却 |
 | `COOLDOWN_SECONDS` | `300` | 冷却时间（秒） |
 
@@ -196,8 +213,9 @@ GIT_PASSWORD=<仅 read_repository 权限的 Personal Access Token>
 
 | 命令 | 说明 |
 |------|------|
+| `up` | **一键部署**：build + start + watchdog（强制重来），启动后等待就绪 |
 | `build` | 构建前端、创建 Python 虚拟环境、安装所有依赖 |
-| `start` | 后台启动服务 |
+| `start` | 后台启动服务（强制重启并等待 `/api/health` 就绪；端口被非本项目进程占用会报错） |
 | `stop` | 停止服务和 watchdog |
 | `restart` | 重启服务 |
 | `status` | 查看服务和 watchdog 运行状态 |
@@ -209,18 +227,17 @@ GIT_PASSWORD=<仅 read_repository 权限的 Personal Access Token>
 ### 常用操作
 
 ```bash
-# 首次部署
+# 首次部署（一键：build + start + watchdog）
-./deploy.sh build && ./deploy.sh start
+./deploy.sh up
 
 # 查看状态
 ./deploy.sh status
 
 # 更新代码后重新部署
 git pull
-./deploy.sh build
+./deploy.sh up
-./deploy.sh restart
 
-# 启用健康监测
+# 单独启用健康监测
 ./deploy.sh watchdog
 
 # 停止所有服务
@@ -370,6 +387,31 @@ launchctl load ~/Library/LaunchAgents/com.readoor.buildserver.watchdog.plist
 
 ---
 
+## 推送代码到 Git 服务器
+
+本项目托管在自建 Git 服务（`origin` 走 HTTPS），推送需要账号凭据：
+
+```bash
+# 提交改动
+git add -A
+git commit -m "feat: 描述你的改动"
+
+# 推送到远程 main
+git push origin main
+```
+
+首次推送会提示输入用户名和密码/访问令牌。若不想每次都输入，可启用 macOS 钥匙串缓存凭据（只需配置一次）：
+
+```bash
+git config --global credential.helper osxkeychain
+```
+
+配置后，下一次 `git push` 输入的账号密码会被安全保存到钥匙串，后续免输入。
+
+> 若 Git 服务使用**访问令牌**认证：用户名填账号、密码填令牌即可。
+
+---
+
 ## 自动化测试
 
 ### 运行测试