docs: GIS Actions 部署文档（基于代码实际分析）

suites-help/系统使用手册/GIS-Actions-本地部署.md

@@ -1,56 +1,122 @@
 # GIS Actions 本地部署
 
-> **状态：待发布。** gis-actions 的安装包和安装文档目前尚未就绪。
-> 本文档记录部署方案，当前仅供参考。
+## 是什么
 
-GIS Actions 是套件的本地执行引擎，跑在你的机器上。
+GIS Actions 是套件的本地执行引擎。它在你的机器上跑一个后台进程，从调度中心拉取任务，在 Docker 中执行。
 
 ## 前提条件
 
 - **Python 3.10+**
-- **Docker**
-- 能访问 `registry.mercator.cn`（拉取 gis-base 镜像）
+- **Docker**（验证：`docker ps`）
+- 能访问 `suites.mercator.cn` 和 `registry.mercator.cn`
 
-## 安装方式（规划中）
+## 依赖
 
-| 平台 | 方式 | 状态 |
-|------|------|------|
-| Linux | 待定 | 待构建 |
-| Windows | installer | 待构建 |
-| macOS | Homebrew / .dmg | 待构建 |
-| 跨平台 | `pip install gis-actions` | 待发布到 PyPI |
+GIS Actions 使用 Python 标准库，无第三方包依赖。
+所有 GIS 计算在 Docker 容器中完成，不需要在你的机器上安装 GDAL 等库。
+
+## 获取代码
+
+### 方案 A：从 Gitea Packages 下载
+
+```bash
+curl -L -o gis-actions.tar.gz \
+  "https://git.mercator.cn/api/packages/AgentGIS/generic/gis-actions/2.2.2/gis-actions.tar.gz"
+tar xzf gis-actions.tar.gz
+cd gis-actions
+```
+
+### 方案 B：从 git 仓库获取（需仓库访问权限）
+
+```bash
+git clone https://git.mercator.cn/AgentGIS/gis-actions.git
+cd gis-actions
+```
 
 ## 配置
 
-需要创建配置文件，包含以下信息：
+创建 `worker.json`：
 
-- **Worker ID**：唯一标识你的机器
-- **Scheduler URL**：`https://suites.mercator.cn`
-- **API Key**：从 https://auth.mercator.cn 获取
+```json
+{
+  "worker": {
+    "id": "my-machine-001",
+    "capabilities": ["gis-operations"]
+  },
+  "scheduler": {
+    "url": "https://suites.mercator.cn",
+    "poll_interval": 5,
+    "heartbeat_interval": 30
+  },
+  "auth": {
+    "api_key": "***"
+  },
+  "logging": {
+    "level": "INFO",
+    "file": "/var/log/gis-actions.log"
+  }
+}
+```
+
+API Key 从 https://auth.mercator.cn 获取。
 
 ## 启动
 
 ```bash
-python3 worker.py --config config.json
+python3 worker.py --config worker.json
 ```
 
-启动后自动连接调度中心，注册自身，开始等待任务。
+启动后自动注册到调度中心，开始轮询任务。
+
+## 验证
+
+日志中应看到：
+
+```
+Worker my-machine-001 started, polling https://suites.mercator.cn every 5s
+Worker registered successfully
+```
+
+## 进程管理
+
+建议使用进程管理工具保持后台运行：
+
+**Linux：**
+```bash
+# 使用 nohup
+nohup python3 worker.py --config worker.json > gis-actions.log 2>&1 &
+
+# 或 supervisor（推荐）
+# 配置见 packaging/deb/ 目录
+```
+
+**Windows / macOS：** 可放入开机启动脚本或使用进程管理器。
+
+## 停止
+
+```bash
+# 前台运行：Ctrl+C
+# 后台运行：kill 进程
+```
+
+停止时自动发送下线心跳。
 
 ## 数据流向
 
 ```
-你本地的 SHP/GeoJSON/TIFF 文件
+你的 SHP/GeoJSON/TIFF 文件（本地路径）
     │
     ▼
 GIS Actions（你的机器）
-    │  ← 从调度中心拉取任务
+    │  ← 轮询调度中心
     │  ← 下载套件脚本包
-    │  ← docker run gis-base + 套件脚本
+    │  ← docker run --rm registry.mercator.cn/agentgis/gis-base:latest
     │  → 结果写入 /tmp/output/
+    │  → 脚本包自动清理
     ▼
-结果文件（你的机器）
+结果文件（你的机器 /tmp/output/）
 ```
 
 ## 架构核心
 
-**数据永不离开本地。** 你的文件始终在你的机器上，GIS Actions 在本地 Docker 容器中处理，不上传到云端。
+**数据永不离开本地。** 你的文件始终在你的机器上处理，不上传到云端。