From fd70af4d56062ff2c2d75db7ea31a8736a1ca664 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AD=A6=E9=98=B3?= <wuy398@chinaunicom.cn>
Date: Thu, 7 May 2026 12:03:00 +0800
Subject: [PATCH] Use user-level deployment by default

---
 README.md                                     | 28 ++++++++++---------
 .../zk-data-agent-backend.service.template    |  1 -
 .../zk-data-agent-frontend.service.template   |  1 -
 scripts/deploy-ubuntu.sh                      | 24 ++++++++--------
 scripts/install-from-git.sh                   |  5 ++--
 5 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 0e0828b..90aa7aa 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,9 @@ ZK Data Agent 是面向中控数据开发流程的 Agent 服务。当前仓库
 适合首次部署，也适合后续更新：
 
 ```bash
-APP_DIR="/opt/zk-data-agent" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '
+APP_DIR="$HOME/zk-data-agent" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '
 set -euo pipefail
 
-sudo mkdir -p "$APP_DIR"
-sudo chown "$USER":"$USER" "$APP_DIR"
-
 if [ -d "$APP_DIR/.git" ]; then
   cd "$APP_DIR"
   git fetch origin
@@ -37,7 +34,7 @@ bash scripts/deploy-ubuntu.sh "$BRANCH" --skip-git
 修改部署目录或分支时，只需要调整命令开头的变量：
 
 ```bash
-APP_DIR="/data/zk-data-agent" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '...'
+APP_DIR="$HOME/zk-data-agent-test" BRANCH="main" REPO="git@git.n.xiaomi.com:wuyang6/zk-data-agent.git" bash -lc '...'
 ```
 
 这个命令会自动完成：
@@ -100,7 +97,7 @@ cp .env.deploy.example .env.deploy
 
 ## 运行方式
 
-部署脚本会安装两个 systemd 服务：
+部署脚本会安装两个用户级 systemd 服务，不需要 sudo：
 
 ```bash
 zk-data-agent-backend
@@ -110,27 +107,27 @@ zk-data-agent-frontend
 查看状态：
 
 ```bash
-sudo systemctl status zk-data-agent-backend
-sudo systemctl status zk-data-agent-frontend
+systemctl --user status zk-data-agent-backend
+systemctl --user status zk-data-agent-frontend
 ```
 
 查看日志：
 
 ```bash
-sudo journalctl -u zk-data-agent-backend -f
-sudo journalctl -u zk-data-agent-frontend -f
+journalctl --user -u zk-data-agent-backend -f
+journalctl --user -u zk-data-agent-frontend -f
 ```
 
 重启服务：
 
 ```bash
-sudo systemctl restart zk-data-agent-backend zk-data-agent-frontend
+systemctl --user restart zk-data-agent-backend zk-data-agent-frontend
 ```
 
 停止服务：
 
 ```bash
-sudo systemctl stop zk-data-agent-backend zk-data-agent-frontend
+systemctl --user stop zk-data-agent-backend zk-data-agent-frontend
 ```
 
 ## 本地开发启动
@@ -155,7 +152,6 @@ Ubuntu 部署建议准备：
 - `git`
 - `bash`
 - `curl`
-- `sudo`
 - `systemd`
 - `pyenv`
 - Python `3.10.14`
@@ -166,6 +162,12 @@ Python 后端依赖由部署脚本安装到项目根目录 `.venv`。
 
 前端依赖由部署脚本在 `frontend/app` 下执行 `npm ci` 安装，并执行 `npm run build`。
 
+默认部署使用用户级 systemd，不需要 sudo。若机器要求服务在用户退出 SSH 后仍保持运行，可由管理员额外执行：
+
+```bash
+loginctl enable-linger <username>
+```
+
 ## 目录说明
 
 ```text
diff --git a/deploy/systemd/zk-data-agent-backend.service.template b/deploy/systemd/zk-data-agent-backend.service.template
index e5c4d15..935efb7 100644
--- a/deploy/systemd/zk-data-agent-backend.service.template
+++ b/deploy/systemd/zk-data-agent-backend.service.template
@@ -5,7 +5,6 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-User=__USER__
 WorkingDirectory=__PROJECT_ROOT__
 ExecStart=__PROJECT_ROOT__/scripts/start-backend.sh
 Restart=always
diff --git a/deploy/systemd/zk-data-agent-frontend.service.template b/deploy/systemd/zk-data-agent-frontend.service.template
index 961e8e3..f156047 100644
--- a/deploy/systemd/zk-data-agent-frontend.service.template
+++ b/deploy/systemd/zk-data-agent-frontend.service.template
@@ -5,7 +5,6 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-User=__USER__
 WorkingDirectory=__PROJECT_ROOT__/frontend/app
 ExecStart=__PROJECT_ROOT__/scripts/start-frontend.sh
 Restart=always
diff --git a/scripts/deploy-ubuntu.sh b/scripts/deploy-ubuntu.sh
index 998c29f..15afcd9 100755
--- a/scripts/deploy-ubuntu.sh
+++ b/scripts/deploy-ubuntu.sh
@@ -3,13 +3,14 @@ set -euo pipefail
 
 # Ubuntu 一键部署/更新脚本。
 # - 首次执行会交互式生成 .env.deploy，本机保存，不提交 git。
-# - 后续执行会拉取代码、更新依赖、构建前端、安装/重启 systemd 服务。
+# - 后续执行会拉取代码、更新依赖、构建前端、安装/重启用户级 systemd 服务。
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ENV_FILE="${ROOT_DIR}/.env.deploy"
 PYTHON_VERSION="${PYTHON_VERSION:-3.10.14}"
 BACKEND_SERVICE="zk-data-agent-backend"
 FRONTEND_SERVICE="zk-data-agent-frontend"
+USER_SYSTEMD_DIR="${HOME}/.config/systemd/user"
 BRANCH=""
 FORCE=0
 SKIP_GIT=0
@@ -210,31 +211,30 @@ build_frontend() {
 install_systemd_service() {
 	local service_name="$1"
 	local template_path="$2"
-	local target_path="/etc/systemd/system/${service_name}.service"
+	local target_path="${USER_SYSTEMD_DIR}/${service_name}.service"
 	local tmp_path
 	tmp_path="$(mktemp)"
+	mkdir -p "${USER_SYSTEMD_DIR}"
 	sed \
 		-e "s#__PROJECT_ROOT__#${ROOT_DIR}#g" \
-		-e "s#__USER__#$(id -un)#g" \
 		"${template_path}" >"${tmp_path}"
-	sudo install -m 0644 "${tmp_path}" "${target_path}"
+	install -m 0644 "${tmp_path}" "${target_path}"
 	rm -f "${tmp_path}"
 }
 
 install_services() {
 	require_command systemctl "当前系统不支持 systemd，无法安装服务。"
-	require_command sudo "安装 systemd 服务需要 sudo。"
-	log "安装/更新 systemd 服务"
+	log "安装/更新用户级 systemd 服务"
 	install_systemd_service "${BACKEND_SERVICE}" "${ROOT_DIR}/deploy/systemd/${BACKEND_SERVICE}.service.template"
 	install_systemd_service "${FRONTEND_SERVICE}" "${ROOT_DIR}/deploy/systemd/${FRONTEND_SERVICE}.service.template"
-	sudo systemctl daemon-reload
-	sudo systemctl enable "${BACKEND_SERVICE}" "${FRONTEND_SERVICE}"
+	systemctl --user daemon-reload
+	systemctl --user enable "${BACKEND_SERVICE}" "${FRONTEND_SERVICE}"
 }
 
 restart_services() {
 	log "重启服务"
-	sudo systemctl restart "${BACKEND_SERVICE}"
-	sudo systemctl restart "${FRONTEND_SERVICE}"
+	systemctl --user restart "${BACKEND_SERVICE}"
+	systemctl --user restart "${FRONTEND_SERVICE}"
 }
 
 health_check() {
@@ -253,8 +253,8 @@ health_check() {
 		sleep 0.5
 	done
 	warn "健康检查失败，输出最近日志。"
-	sudo journalctl -u "${BACKEND_SERVICE}" -n 80 --no-pager || true
-	sudo journalctl -u "${FRONTEND_SERVICE}" -n 80 --no-pager || true
+	journalctl --user -u "${BACKEND_SERVICE}" -n 80 --no-pager || true
+	journalctl --user -u "${FRONTEND_SERVICE}" -n 80 --no-pager || true
 	exit 1
 }
 
diff --git a/scripts/install-from-git.sh b/scripts/install-from-git.sh
index 7be29ea..ca8532e 100755
--- a/scripts/install-from-git.sh
+++ b/scripts/install-from-git.sh
@@ -1,12 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# 适合 README 中 curl | bash 的安装入口。
-# 它只负责 clone/pull 仓库，然后调用仓库内 scripts/deploy-ubuntu.sh。
+# 从 git 拉取/更新仓库，然后调用仓库内 scripts/deploy-ubuntu.sh。
 
 REPO="${REPO:-git@git.n.xiaomi.com:wuyang6/zk-data-agent.git}"
 BRANCH="${BRANCH:-main}"
-APP_DIR="${APP_DIR:-/opt/zk-data-agent}"
+APP_DIR="${APP_DIR:-${HOME}/zk-data-agent}"
 FORCE=0
 
 usage() {