From 3fd6ba3baf5e8d8ff222f6bda5d1f0ccf662f80f Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Wed, 12 Aug 2026 11:08:55 +0800
Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E6=9B=B4=E6=96=B0=E9=83=A8?=
 =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3=E4=B8=BA=E7=9B=AE=E5=BD=95=E8=87=AA?=
 =?UTF-8?q?=E9=80=82=E5=BA=94=20+=20=E6=96=B0=E5=A2=9E=E7=94=9F=E4=BA=A7?=
 =?UTF-8?q?=E6=9C=8D=E5=8A=A1=E5=99=A8=E6=9B=B4=E6=96=B0=E6=B5=81=E7=A8=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. 生产部署建议改为推荐 start.sh 自动化方式（目录自适应、
   systemd 自动生成与开机自启、崩溃自动重启）。
2. 新增「生产服务器更新流程」：git pull 拉到最新代码后
   systemctl restart 三个服务即可，附完整验证命令。
3. 移除旧的手动创建 systemd 单元的过时文档（硬编码 /root/ipam）。
4. 统一把文档里的 /root/ipam 硬编码改为 <项目目录> 中性占位符。
---
 README.md | 191 ++++++++++++++++++++++++++++++++----------------------
 1 file changed, 113 insertions(+), 78 deletions(-)

diff --git a/README.md b/README.md
index 2ce7d45..549dba6 100644
--- a/README.md
+++ b/README.md
@@ -53,46 +53,55 @@
 ### 一键启动所有服务
 
 #### 方式一：使用启动脚本（推荐）
+
+`start.sh` 目录自适应，无论部署在 `/opt`、`/usr/local`、`/root` 还是其它任意目录，
+直接以脚本所在目录为项目根运行即可（需 root 权限）：
+
 ```bash
-cd /root/ipam
-./start.sh
+cd /你的部署目录     # 例如 /opt/ipam，跟随你实际的部署路径
+bash start.sh
 ```
 
+运行时会自动：创建 Python venv → 安装后端依赖 → 启动 MySQL/Redis 容器 →
+生成 3 个 systemd 服务（backend / celery-worker / celery-beat）并 enable 开机自启 →
+启动前端。更多细节见下文「生产环境部署建议」。
+
 #### 方式二：手动启动
 
+> ⚠️ 仅供开发调试用。生产环境推荐使用方式一（start.sh），可自动生成 systemd 服务、开机自启、崩溃自动重启。
 
 #### 安装依赖环境
 ```bash
-cd /root/ipam/backend
+# 以下 <项目目录> 均指你实际的部署路径，例如 /opt/ipam
+cd <项目目录>/backend
 source venv/bin/activate
 pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"
-apt install -y celery
 ```
 
 ##### 1️⃣ 启动后端 API 服务
 ```bash
-cd /root/ipam/backend
+cd <项目目录>/backend
 source venv/bin/activate
 uvicorn app.main:app --host 0.0.0.0 --port 8008
 ```
 
 ##### 2️⃣ 启动 Celery Worker（执行扫描任务）
 ```bash
-cd /root/ipam/backend
+cd <项目目录>/backend
 source venv/bin/activate
 celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
 ```
 
 ##### 3️⃣ 启动 Celery Beat（定时任务调度器，自动扫描必须启动）
 ```bash
-cd /root/ipam/backend
+cd <项目目录>/backend
 source venv/bin/activate
 celery -A app.tasks.celery_app beat --loglevel=info
 ```
 
 ##### 4️⃣ 启动前端
 ```bash
-cd /root/ipam/frontend
+cd <项目目录>/frontend
 npm install
 npm run dev -- --host 0.0.0.0 --port 3000
 ```
@@ -113,7 +122,7 @@ npm run dev -- --host 0.0.0.0 --port 3000
 
 ### 如何自定义扫描频率
 
-编辑配置文件：`/root/ipam/backend/app/tasks/celery_app.py`
+编辑配置文件：`<项目目录>/backend/app/tasks/celery_app.py`
 
 ```python
 # 定时任务配置 (第 36-55 行)
@@ -169,7 +178,7 @@ celery_app.conf.beat_schedule = {
 
 #### 查看 Celery 活跃任务
 ```bash
-cd /root/ipam/backend
+cd <项目目录>/backend
 source venv/bin/activate
 celery -A app.tasks.celery_app inspect active
 ```
@@ -188,83 +197,109 @@ celery -A app.tasks.celery_app inspect stats
 
 ## 🛠️ 生产环境部署建议
 
-### 使用 Systemd 管理服务（开机自启）
+### 推荐方式：使用 start.sh（自动化，目录自适应）
 
-#### 1. 创建 IPAM API 服务
-```ini
-# /etc/systemd/system/ipam-api.service
-[Unit]
-Description=IPAM API Service
-After=network.target mysql.service redis.service
+`start.sh` 已内置完整的生产级部署逻辑，**无需手动创建任何 systemd 单元**：
 
-[Service]
-Type=simple
-User=root
-WorkingDirectory=/root/ipam/backend
-Environment="PATH=/root/ipam/backend/venv/bin"
-ExecStart=/root/ipam/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8008
-Restart=always
-RestartSec=10
+- **目录自适应**：不硬编码路径，自动以脚本所在目录为项目根。无论部署在
+  `/opt/ipam`、`/usr/local/ipam`、`/root/ipam` 还是其它任意目录都能工作。
+- **systemd 自动生成**：运行 `start.sh` 时自动生成并 `systemctl enable` 如下
+  3 个服务，实现**开机自启** + **崩溃自动重启**（`Restart=always`）：
 
-[Install]
-WantedBy=multi-user.target
-```
+  | 服务名 | 内容 | 说明 |
+  |--------|------|------|
+  | `ipam-backend` | uvicorn :8008 | 后端 API |
+  | `ipam-celery-worker` | celery worker | 执行扫描/轮询任务 |
+  | `ipam-celery-beat` | celery beat | 定时任务调度器（每60秒触发 SNMP 设备自动轮询） |
 
-#### 2. 创建 Celery Worker 服务
-```ini
-# /etc/systemd/system/ipam-celery-worker.service
-[Unit]
-Description=IPAM Celery Worker
-After=network.target redis.service
+  日志写入 `/var/log/ipam/*.log`。
 
-[Service]
-Type=simple
-User=root
-WorkingDirectory=/root/ipam/backend
-Environment="PATH=/root/ipam/backend/venv/bin"
-ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
-Restart=always
-RestartSec=10
+#### 首次部署（全新机器）
 
-[Install]
-WantedBy=multi-user.target
-```
-
-#### 3. 创建 Celery Beat 服务
-```ini
-# /etc/systemd/system/ipam-celery-beat.service
-[Unit]
-Description=IPAM Celery Beat Scheduler
-After=network.target redis.service
-
-[Service]
-Type=simple
-User=root
-WorkingDirectory=/root/ipam/backend
-Environment="PATH=/root/ipam/backend/venv/bin"
-ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app beat --loglevel=info
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-#### 4. 启用并启动服务
 ```bash
-# 重新加载配置
-systemctl daemon-reload
+# 1. 前置：Python3 / Node.js / Docker 需已安装
+# 2. git clone 代码（放到你想要的任何目录）
+git clone https://git.cnbugs.com/AI-Agent/ipam.git /opt/ipam
+cd /opt/ipam
 
-# 启用开机自启
-systemctl enable ipam-api ipam-celery-worker ipam-celery-beat
-
-# 启动服务
-systemctl start ipam-api ipam-celery-worker ipam-celery-beat
-
-# 查看服务状态
-systemctl status ipam-api ipam-celery-worker ipam-celery-beat
+# 3. 一键启动（需 root 权限，自动装依赖 + 起 MySQL/Redis 容器 + 生成 systemd + 启前端）
+bash start.sh
 ```
 
+启动成功后即可访问：
+- 管理界面 `http://服务器IP:3000`
+- API 文档 `http://服务器IP:8008/docs`
+
+> 💡 首次运行 `start.sh` 会自动创建 Python venv、安装前端依赖（含 vite）、
+> 启动 MySQL/Redis Docker 容器、生成 3 个 systemd 服务并 enable 开机自启，
+> 全程无需人工干预。若部署目录想换到别处，把项目整个复制过去再跑一次
+> `bash start.sh` 即可自动重写 systemd 单元。
+
+#### 服务管理命令
+
+```bash
+# 启动 / 停止 / 重启
+bash start.sh
+bash stop.sh
+
+# 查看状态（开机自启 + 运行中）
+systemctl status ipam-backend ipam-celery-worker ipam-celery-beat
+
+# 查看日志
+tail -f /var/log/ipam/ipam-backend.log
+tail -f /var/log/ipam/ipam-celery-worker.log
+tail -f /var/log/ipam/ipam-celery-beat.log
+```
+
+---
+
+### 生产服务器更新流程（git 部署时）
+
+生产代码是通过 `git clone` 放上去的，日常更新用 `git pull` 拉取远端最新代码，
+再重启服务即可。**推荐更新流程**：
+
+```bash
+cd /你的部署目录            # 例如 /opt/ipam，跟随你实际的部署路径
+
+# 1.（可选）备份当前脚本，防止意外
+cp start.sh /tmp/start.sh.bak
+
+# 2. 拉取远端最新代码（含全部修复：单IP扫描、SNMP自动轮询、告警检测、部署脚本）
+git pull origin master
+
+# 3. 重启服务让新代码生效（需 root）
+#    - 后端 / Celery Worker / Celery Beat 是 systemd 管理，重启它们即可
+systemctl restart ipam-backend ipam-celery-worker ipam-celery-beat
+
+#    - 前端 vite dev server 是 nohup 方式，需手动重启：
+pkill -f "vite" ; sleep 2
+cd frontend && nohup npm run dev -- --host 0.0.0.0 --port 3000 > /tmp/ipam-frontend.log 2>&1 &
+
+# 4. 全量一键启动（更省心：自动检测目录重新生成 systemd + 拉起全部服务）
+#    bash start.sh
+
+# 5. 验证服务全部正常
+systemctl is-active ipam-backend ipam-celery-worker ipam-celery-beat   # 应输出 3 个 active
+curl -s http://localhost:8008/health                                   # 后端健康
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000           # 前端 200
+```
+
+**更新要点：**
+
+1. **后端 / Celery 是 systemd 管理**（ipam-backend / ipam-celery-worker /
+   ipam-celery-beat），更新代码后只需 `systemctl restart` 这三个服务，
+   它们会保持开机自启和崩溃自动重启。
+2. **前端是 nohup 方式**（vite dev server，开发服务不纳入 systemd），需要
+   `pkill -f vite` 后重新 `npm run dev` 启动。
+3. **依赖变更时**：若 `git pull` 拉取后要求新 Python 包，执行
+   `cd backend && venv/bin/pip install -r requirements.txt`；
+   前端依赖变化则 `cd frontend && npm install --include=dev`。
+4. **若你切换了部署目录**（从 /opt 挪到 /usr/local 等），直接在新位置跑一次
+   `bash start.sh`，它会自动按新目录重新生成 systemd 单元，无需手动改任何配置。
+5. **首次部署到新机器**建议直接跑 `bash start.sh`（一键全自动），日常增量更新
+   用第 2~4 步的重启方式即可，两者效果一致。
+
+
 ---
 
 ## 🌐 访问地址
@@ -358,7 +393,7 @@ A: 1. 增加并发数 2. 关闭 DNS 解析（较慢）3. 分网段分时段扫
 ## 📁 项目结构
 
 ```
-/root/ipam/
+<项目目录>/            # 例如 /opt/ipam、/usr/local/ipam，任意目录均可
 ├── backend/
 │   ├── app/
 │   │   ├── api/v1/           # API 路由