lingshu/offline_package

灵枢智能任务平台 - 离线部署包
================================

【Windows 用户操作步骤】
  前置条件：
    1. 安装 WSL 2：以管理员身份打开 PowerShell，执行：
         wsl --install
       完成后重启电脑，弹出 Ubuntu 窗口时随便设置用户名密码。
    2. 安装 Docker Desktop：https://www.docker.com/products/docker-desktop/
       安装完成后，右键任务栏 Docker 图标 → 选 "Switch to Linux containers..."
       等待 Docker 图标变为绿色稳定状态。
  部署步骤（一键）：
    1. 将压缩包解压到某个目录，如 C:\lingshu\
    2. 双击运行 deploy_windows.bat（或右键 → 以管理员身份运行）
    3. 脚本自动完成导入镜像、解压代码、启动服务，完成后浏览器访问：
         http://localhost:5000
  注意：Windows Server 2007 及以下版本不支持，请使用 Win10/Win11 或 Server 2019+。

【WSL 用户操作步骤】
  前置条件：已安装 WSL 2（Ubuntu 20.04/22.04）及 Docker Desktop（Linux 容器模式）。
  部署步骤（一键）：
    1. 将压缩包解压到 WSL 目录，如 ~/lingshu_pkg/
    2. 在 WSL 终端执行：
         cd ~/lingshu_pkg
         chmod +x deploy_on_server.sh
         sudo ./deploy_on_server.sh
    3. 脚本自动完成全部操作，完成后浏览器访问：http://localhost:5000

【Ubuntu 用户操作步骤】
  前置条件：已安装 Docker Engine 20.10+ 及 Docker Compose V2。
    若未安装 Docker，执行：
      sudo apt update && sudo apt install -y docker.io docker-compose-v2
      sudo systemctl start docker
  部署步骤（一键）：
    1. 将压缩包解压到某目录，如 ~/lingshu_pkg/
    2. 在终端执行：
         cd ~/lingshu_pkg
         chmod +x deploy_on_server.sh
         sudo ./deploy_on_server.sh
    3. 脚本自动完成全部操作，完成后终端会显示访问地址，浏览器打开即可。
  若 3306 端口被占用（本地有 MySQL），脚本会自动改为 3307，无需手动处理。




【默认账号】
  用户名：admin
  密  码：admin123

【刻盘内容】
  mysql_8.0.tar.gz      - MySQL 8.0 Docker 镜像
  lingshu_app.tar.gz    - 灵枢应用 Docker 镜像
  lingshu_code.tar.gz   - 项目代码（含配置）
  deploy_on_server.sh   - 一键部署脚本
  README.txt            - 本说明文件

【服务器环境要求】
  - Linux (x86_64)
  - Docker Engine 20.10+（需提前在服务器安装）
  - Docker Compose V2（docker compose 命令）
  - 不需要联网


【OpenClaw 说明】
  本平台在无 OpenClaw 的环境下可完整运行。
  任务调度将使用内置模拟执行引擎，所有功能（
  任务管理、执行记录、日志、告警、团队协作）均正常可用。

【端口说明】
  - 5000: 灵枢 Web 平台（对外访问）
  - 3306: MySQL（仅内部使用，如冲突自动改为 3307）

================================================================
【机房保密服务器对接 OpenClaw 完整操作指南】
================================================================

  机房已部署的环境（无需重复安装）：
    - Ubuntu 20.04 LTS
    - Docker CE + NVIDIA Container Toolkit
    - MySQL 8.0（支持远程访问）
    - Ollama（含 Qwen3.5 大模型，离线已校验）
    - Dify v0.6.x（完整微服务集群）
    - OpenClaw 源码（位于 /data/OpenClaw_resources）

  ----------------------------------------------------------------
  第一步：将光盘内容拷贝到服务器并部署灵枢
  ----------------------------------------------------------------
    1. 将光盘内容复制到服务器，例如：
         cp -r /media/cdrom/ /opt/lingshu_pkg/
         cd /opt/lingshu_pkg

    2. 赋予部署脚本执行权限并运行：
         chmod +x deploy_on_server.sh
         sudo ./deploy_on_server.sh

    3. 等待脚本执行完毕，验证灵枢是否正常启动：
         docker compose ps
       看到 lingshu_app 和 lingshu_db 均为 Up 状态即成功。

    4. 浏览器访问 http://服务器IP:5000，能看到登录页面说明部署成功。
       默认账号：admin / admin123

  ----------------------------------------------------------------
  第二步：启动 OpenClaw 服务
  ----------------------------------------------------------------
    1. 进入 OpenClaw 资源目录：
         cd /data/OpenClaw_resources

    2. 查看目录内容，找到启动方式：
         ls -la

    3. 若为 Docker 方式启动：
         docker compose up -d
       若为 Python 直接运行：
         pip install -r requirements.txt
         python main.py
       （具体启动命令以机房老师说明为准）

    4. 确认 OpenClaw 端口（默认 18789），验证是否启动成功：
         curl http://127.0.0.1:18789/api/health
       返回 JSON 且状态码为 200 说明 OpenClaw 已就绪。

    5. 记下 OpenClaw 的实际监听端口，后续步骤需要用到。

  ----------------------------------------------------------------
  第三步：在 Dify 后台注册 Ollama 模型
  ----------------------------------------------------------------
    1. 浏览器打开 Dify 管理后台：
         http://服务器IP:80   （或 :3000，以实际端口为准）

    2. 用管理员账号登录（账号密码询问机房老师）。

    3. 点击右上角头像 → 设置 → 模型供应商。

    4. 找到 "Ollama"，点击添加模型：
         模型类型：LLM
         模型名称：qwen3.5（或 ollama 中实际的模型名）
         基础 URL：http://127.0.0.1:11434
                  （若 Ollama 是 Docker 容器，地址可能是 http://ollama:11434）
       保存后点击"测试连通性"，显示绿色成功即可。

    5. 验证模型可用：在 Dify 首页新建一个对话，选择 Qwen3.5，
       随便发一条消息，能收到回复说明模型已接通。

  ----------------------------------------------------------------
  第四步：在 Dify 里创建并发布智能体（Agent）
  ----------------------------------------------------------------
    1. 在 Dify 首页点击"创建应用" → 选择"Agent"类型。

    2. 配置 Agent 基本信息：
         名称：根据任务命名，如"情报摘要Agent"
         模型：选择上一步注册好的 Qwen3.5
         系统提示词（soul.md 内容）：填写 Agent 的角色定位，例如：
           "你是一个军事情报摘要助手，负责将原始侦察日志提炼为
            结构化简报，输出格式为：时间、地点、事件、建议动作。"

    3. 根据需要添加工具（Tools）：
         - 数据库查询工具（连接 MySQL 读取业务数据）
         - HTTP 请求工具（调用外部接口）
         - 文件读写工具（读取/写入侦察日志）

    4. 配置完成后，点击右上角"发布"。

    5. 发布后进入"API 访问"页面，记录以下信息（后续需要）：
         API 地址：http://服务器IP:80/v1/...
         API Key：sk-xxxxxxxxxxxxxxxx

  ----------------------------------------------------------------
  第五步：将 Dify Agent 接口配置到 OpenClaw
  ----------------------------------------------------------------
    1. 进入 OpenClaw 配置目录：
         cd /data/OpenClaw_resources

    2. 找到配置文件（通常为 config.yaml 或 .env）：
         ls *.yaml *.env config/ 2>/dev/null

    3. 在配置文件中填入 Dify Agent 的 API 地址和 Key，例如：
         dify_api_url: http://127.0.0.1:80/v1
         dify_api_key: sk-xxxxxxxxxxxxxxxx

    4. 保存配置后重启 OpenClaw：
         docker compose restart
       或
         Ctrl+C 后重新运行 python main.py

  ----------------------------------------------------------------
  第六步：修改灵枢连接 OpenClaw 的地址
  ----------------------------------------------------------------
    1. 编辑灵枢的 docker-compose.yml：
         nano /opt/lingshu/docker-compose.yml

    2. 找到 app 服务的 environment 段，修改 OPENCLAW_URL：
         environment:
           OPENCLAW_URL: http://127.0.0.1:18789   ← 改为 OpenClaw 实际端口

       若 OpenClaw 不在同一台机器，地址改为对应服务器 IP，例如：
         OPENCLAW_URL: http://192.168.1.100:18789

    3. 保存后重启灵枢 app 容器：
         cd /opt/lingshu
         docker compose restart app

    4. 验证连接是否成功：
         curl http://localhost:5000/api/openclaw/status
       返回 "connected": true 说明灵枢已成功对接 OpenClaw。

  ----------------------------------------------------------------
  第七步：端到端验证
  ----------------------------------------------------------------
    1. 浏览器打开 http://服务器IP:5000，用 admin / admin123 登录。

    2. 进入"配置中心"，查看 AI 引擎状态，确认 OpenClaw 显示"在线"。

    3. 进入"任务中心"，新建一个测试任务：
         触发方式：手动触发
         Skill：填写 Dify Agent 中配置的 skill 名称
         保存后点击"手动执行一次"

    4. 点击"监控"查看执行日志：
         - 若日志显示"OpenClaw 已接受任务"说明调度链路打通。
         - 若日志显示"模拟执行"说明 OpenClaw 还未连通，检查第六步。

    5. 全链路打通后，可正式启动定时任务（设置 Cron 表达式），
       任务将按时自动触发 → OpenClaw 调度 → Dify Agent 执行 →
       Qwen3.5 推理 → 结果回调写入灵枢数据库 → 前端实时展示。

  ----------------------------------------------------------------
  常见问题排查
  ----------------------------------------------------------------
    Q: curl OpenClaw health 返回 Connection refused
    A: OpenClaw 未启动，回到第二步重新启动，检查端口是否正确。

    Q: Dify 模型测试失败
    A: 检查 Ollama 容器是否在运行：docker ps | grep ollama
       检查模型是否已加载：curl http://127.0.0.1:11434/api/tags

    Q: 灵枢配置中心显示 OpenClaw 离线，但服务已启动
    A: 检查 docker-compose.yml 中 OPENCLAW_URL 地址和端口是否正确，
       注意灵枢 app 容器内访问宿主机需用 host.docker.internal 或宿主机实际 IP，
       不能用 127.0.0.1（容器内的 127.0.0.1 是容器自身）。
       修复方法：将 OPENCLAW_URL 改为宿主机 IP，例如：
         OPENCLAW_URL: http://172.17.0.1:18789
       然后执行：docker compose restart app

    Q: 任务执行显示"模拟执行"而非真实执行
    A: 说明灵枢调用 OpenClaw 失败，走了降级逻辑。
       按上一条排查 OpenClaw 连接问题。

    Q: Dify Agent 调用报 401 Unauthorized
    A: API Key 填写有误，回到第四步重新复制 API Key。

================================================================