feat: 更新文档，添加 Agent 部署步骤和说明，优化安装脚本以支持安全升级

README.md

@@ -56,14 +56,44 @@ _✨ control plane for reverse proxy management ✨_
 
 ## 快速开始
 
-- [docs/deployment.md](/Users/ryan/DEV/Go/ATSFlare/docs/deployment.md)
+### 1. 启动 Server
+
+先按部署文档启动控制面，默认访问地址为 `http://localhost:3000`。
+
+- [docs/deployment.md](./docs/deployment.md)
+
+### 2. 使用 Discovery Token 一键部署 Agent
+
+适用于新节点首次接入，Agent 会使用全局 `discovery_token` 自动注册并换取节点专属 `agent_token`。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --discovery-token YOUR_DISCOVERY_TOKEN
+```
+
+### 3. 使用 Agent Token 一键部署 Agent
+
+适用于已经在管理端预创建节点、并拿到节点专属 `agent_token` 的场景。
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
+  --server-url http://your-server:3000 \
+  --agent-token YOUR_AGENT_TOKEN
+```
+
+说明：
+
+* `--server-url` 替换为实际控制面地址，例如 `http://192.168.1.10:3000`
+* Linux 默认安装到 `/opt/atsflare-agent`，并创建 `atsflare-agent` systemd 服务
+* 重复执行相同命令可用于升级 Agent 到最新 Release
 
 
 ## 贡献
 
 参与开发请先阅读：
 
-1. [docs/design.md](/Users/ryan/DEV/Go/ATSFlare/docs/design.md)
-2. [docs/development-guidelines.md](/Users/ryan/DEV/Go/ATSFlare/docs/development-guidelines.md)
-3. [docs/development-plan.md](/Users/ryan/DEV/Go/ATSFlare/docs/development-plan.md)
+1. [docs/design.md](./docs/design.md)
+2. [docs/development-guidelines.md](./docs/development-guidelines.md)
+3. [docs/development-plan.md](./docs/development-plan.md)
 

docs/deployment.md

@@ -219,9 +219,16 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/insta
 安装脚本会：
 
 1. 从 GitHub Releases 下载最新 Agent 二进制（`atsflare-agent-{os}-{arch}`）
-2. 生成 `agent.json` 配置文件
-3. 创建 systemd 服务 `atsflare-agent.service`
-4. 启动并启用自启
+2. 先下载到临时文件，再替换安装目录中的 Agent 二进制，避免覆盖运行中进程导致写入失败
+3. 生成 `agent.json` 配置文件
+4. 创建 systemd 服务 `atsflare-agent.service`
+5. 启动并启用自启
+
+说明：
+
+* 脚本可重复执行，用于升级到最新 Release
+* 若检测到已运行的 `atsflare-agent` systemd 服务，会先停止服务、替换二进制，再重新启动
+* 已存在的 `agent.json` 不会被覆盖
 
 ### 7.2 管理端生成部署命令
 

scripts/install-agent.sh

@@ -13,6 +13,7 @@ SERVER_URL=""
 DISCOVERY_TOKEN=""
 AGENT_TOKEN=""
 CREATE_SERVICE="true"
+SERVICE_NAME="atsflare-agent"
 
 usage() {
   cat <<EOF
@@ -80,6 +81,11 @@ fi
 ASSET_NAME="atsflare-agent-${OS}-${ARCH}"
 echo "Detected platform: ${OS}/${ARCH}"
 
+SYSTEMCTL_AVAILABLE="false"
+if command -v systemctl >/dev/null 2>&1; then
+  SYSTEMCTL_AVAILABLE="true"
+fi
+
 # Get latest release download URL
 echo "Fetching latest release from ${REPO}..."
 RELEASE_INFO=$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest")
@@ -99,8 +105,24 @@ mkdir -p "${INSTALL_DIR}/data"
 
 # Download binary
 echo "Downloading ${ASSET_NAME}..."
-curl -fsSL -o "${INSTALL_DIR}/atsflare-agent" "$DOWNLOAD_URL"
-chmod +x "${INSTALL_DIR}/atsflare-agent"
+TMP_BINARY="$(mktemp "${INSTALL_DIR}/atsflare-agent.tmp.XXXXXX")"
+cleanup() {
+  rm -f "$TMP_BINARY"
+}
+trap cleanup EXIT
+
+curl -fsSL -o "$TMP_BINARY" "$DOWNLOAD_URL"
+chmod +x "$TMP_BINARY"
+
+SERVICE_WAS_ACTIVE="false"
+if [[ "$OS" == "linux" && "$SYSTEMCTL_AVAILABLE" == "true" ]] && systemctl is-active --quiet "$SERVICE_NAME"; then
+  SERVICE_WAS_ACTIVE="true"
+  echo "Stopping running service before upgrade..."
+  systemctl stop "$SERVICE_NAME"
+fi
+
+mv -f "$TMP_BINARY" "${INSTALL_DIR}/atsflare-agent"
+trap - EXIT
 
 # Generate config
 CONFIG_FILE="${INSTALL_DIR}/agent.json"
@@ -134,7 +156,7 @@ else
 fi
 
 # Create systemd service
-if [[ "$CREATE_SERVICE" == "true" && "$OS" == "linux" && -d /etc/systemd/system ]]; then
+if [[ "$CREATE_SERVICE" == "true" && "$OS" == "linux" && -d /etc/systemd/system && "$SYSTEMCTL_AVAILABLE" == "true" ]]; then
   echo "Creating systemd service..."
   cat > /etc/systemd/system/atsflare-agent.service <<SVCEOF
 [Unit]
@@ -153,9 +175,13 @@ WantedBy=multi-user.target
 SVCEOF
 
   systemctl daemon-reload
-  systemctl enable atsflare-agent
-  systemctl start atsflare-agent
-  echo "Service created and started: atsflare-agent"
+  systemctl enable "$SERVICE_NAME"
+  systemctl start "$SERVICE_NAME"
+  if [[ "$SERVICE_WAS_ACTIVE" == "true" ]]; then
+    echo "Service restarted with updated binary: ${SERVICE_NAME}"
+  else
+    echo "Service created and started: ${SERVICE_NAME}"
+  fi
 else
   echo ""
   echo "To start the agent manually:"