From 29c5462734c5854911447c8de1118af71a674954 Mon Sep 17 00:00:00 2001
From: zikai <1621362626@qq.com>
Date: Mon, 27 Jul 2026 13:52:23 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20systemd=20?=
 =?UTF-8?q?=E6=8C=81=E4=B9=85=E5=8C=96=E9=83=A8=E7=BD=B2=EF=BC=88deploy/zt?=
 =?UTF-8?q?ools2.service=20+=20install-systemd.sh=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

systemd 管理 zTools2 后端实现开机自启 + 崩溃自动重启：
- deploy/ztools2.service 模板（Restart=on-failure，after mysql）
- deploy/install-systemd.sh 自动检测 .venv 或系统 uvicorn，填充路径安装
- README 补持久化部署章节
---
 README.md                 | 15 +++++++++++
 deploy/install-systemd.sh | 56 +++++++++++++++++++++++++++++++++++++++
 deploy/ztools2.service    | 23 ++++++++++++++++
 3 files changed, 94 insertions(+)
 create mode 100755 deploy/install-systemd.sh
 create mode 100644 deploy/ztools2.service

diff --git a/README.md b/README.md
index 50189da..7a60cbf 100644
--- a/README.md
+++ b/README.md
@@ -184,3 +184,18 @@ systemctl reload apache2
 - **重新生成 DB 密码**：`.venv/bin/python -m app.scripts.init_db`（保留现有：`KEEP_DB_PASSWORD=1`）。
 - **多 worker 限制**：记事本 hub 是进程内存，多 uvicorn worker 下不互通，保持 `workers: 1`。
 - **数据库表**：ORM 启动时自动建表（`init_db_schema`）；`sql/schema.sql` 供参考/手动初始化。
+
+## 持久化部署（systemd）
+
+`./start.sh` 适合手动运维；生产推荐用 systemd 管理实现开机自启 + 崩溃自动重启：
+
+```bash
+./deploy/install-systemd.sh     # 安装并启动 ztools2 服务（开机自启）
+systemctl status ztools2        # 状态
+journalctl -u ztools2 -f        # 日志
+sudo systemctl restart ztools2  # 重启（更新代码后）
+```
+
+脚本自动检测 `.venv/bin/uvicorn` 或系统 `uvicorn`，用实际路径填充 `deploy/ztools2.service` 模板。卸载：`systemctl disable --now ztools2 && rm /etc/systemd/system/ztools2.service && systemctl daemon-reload`。
+
+> 与 zMainPage 整体部署配合：systemd 管后端，`zMainPage/deploy.sh --no-restart` 部署前端。详见 zMainPage 的 [`docs/deployment.md`](https://git.zikai.wang/zikai/zMainPage/src/branch/main/docs/deployment.md)。
diff --git a/deploy/install-systemd.sh b/deploy/install-systemd.sh
new file mode 100755
index 0000000..abd2dc5
--- /dev/null
+++ b/deploy/install-systemd.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# 安装 systemd 服务，实现 zTools2 持久化部署（开机自启 + 崩溃自动重启）。
+#
+# 做的事：
+#   1. 用实际路径填充 deploy/ztools2.service 模板，写入 /etc/systemd/system/
+#   2. 停掉旧方式（start.sh 启动的 uvicorn），避免端口冲突
+#   3. systemctl daemon-reload + enable + start
+#
+# 用法：./deploy/install-systemd.sh
+# 卸载：systemctl disable --now ztools2 && rm /etc/systemd/system/ztools2.service && systemctl daemon-reload
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+ROOT="$(pwd)"
+
+# 解析 uvicorn 可执行路径：优先 .venv（setup.sh 标准），回退系统 python -m uvicorn
+if [[ -x "$ROOT/.venv/bin/uvicorn" ]]; then
+  UVICORN="$ROOT/.venv/bin/uvicorn"
+  PYBIN="$ROOT/.venv/bin/python"
+elif command -v uvicorn >/dev/null 2>&1; then
+  UVICORN="$(command -v uvicorn)"
+  PYBIN="$(command -v python3)"
+else
+  echo "未找到 uvicorn：请先运行 ./setup.sh（建 .venv）或 pip install uvicorn" >&2
+  exit 1
+fi
+[[ -f "$ROOT/config.yaml" ]] || { echo "未找到 config.yaml，请先运行 ./setup.sh" >&2; exit 1; }
+
+UNIT_SRC="$ROOT/deploy/ztools2.service"
+UNIT_DST="/etc/systemd/system/ztools2.service"
+
+echo "==> 生成 systemd unit（路径 $ROOT，uvicorn=$UVICORN）"
+# 同时填充 ROOT 与 UVICORN；PYBIN 备用（ExecStart 用 UVICORN 直接启动）
+sudo sed -e "s|__ZTOOLS2_DIR__|$ROOT|g" -e "s|__UVICORN__|$UVICORN|g" "$UNIT_SRC" > /tmp/ztools2.service
+sudo mv /tmp/ztools2.service "$UNIT_DST"
+sudo chmod 644 "$UNIT_DST"
+
+echo "==> 停止旧方式（start.sh 启动的进程，若有）"
+./stop.sh >/dev/null 2>&1 || true
+
+echo "==> 启用并启动 ztools2 服务"
+sudo systemctl daemon-reload
+sudo systemctl enable ztools2
+sudo systemctl restart ztools2
+
+sleep 2
+if systemctl is-active --quiet ztools2; then
+  echo "✓ ztools2 已启动并设为开机自启"
+  echo "  状态：systemctl status ztools2"
+  echo "  日志：journalctl -u ztools2 -f"
+  echo "  停止：sudo systemctl stop ztools2"
+  echo "  重启：sudo systemctl restart ztools2"
+else
+  echo "✗ ztools2 启动失败，查看日志：journalctl -u ztools2 -n 50" >&2
+  exit 1
+fi
diff --git a/deploy/ztools2.service b/deploy/ztools2.service
new file mode 100644
index 0000000..75b2137
--- /dev/null
+++ b/deploy/ztools2.service
@@ -0,0 +1,23 @@
+[Unit]
+Description=zikai file service (zTools2) - FastAPI backend
+Documentation=https://git.zikai.wang/zikai/zTools2
+After=network.target mysql.service
+Wants=mysql.service
+
+[Service]
+Type=simple
+# 工作目录与 uvicorn 路径：安装时由 install-systemd.sh 用实际路径替换
+WorkingDirectory=__ZTOOLS2_DIR__
+Environment=PYTHONUNBUFFERED=1
+ExecStart=__UVICORN__ app.main:app --host 127.0.0.1 --port 6867 --workers 1
+Restart=on-failure
+RestartSec=3
+# 后台转换可能耗时较长，放宽超时
+TimeoutStopSec=30
+KillSignal=SIGINT
+# 日志走 journald（journalctl -u ztools2）
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target