磐石 是一套可 内网自托管 的 企业级现场管理与数字化平台，围绕五大核心能力构建：Android 设备管理、ESB 系统对接及第三方 SSO、多屏联动工作流、PDA 小屏定制低码平台（Form App）、实时工单系统 + 自定义触发流程可双向对接三方系统。一个浏览器控制台 + 移动端 Agent + 可选本地 USB 桥接，默认使用 SQLite（无需单独装数据库），数据全部留在你自己的服务器。
一句话：Android 设备运维 + ESB 系统集成 + 多屏联动 + PDA 低码表单 + 工单全生命周期管理，企业现场数字化一体方案。
典型用途包括：PDA / 工业手持终端远程管理、现场工单派发与双向对接外部系统、Android 远程桌面与屏幕分享、ESB 企业服务总线集成与第三方 SSO 认证、多屏联动工作流编排、PDA 小屏专用低代码表单录入、组态大屏实时可视化，以及 设备数据采集 → 数据接口 → 外部系统集成 的一体化数据流。
| 你可能在找 | 本仓库提供的能力 |
|---|---|
| Android 设备管理 / PDA 管理 | 设备分组台账、远程画面 + 触控、Web Shell / Logcat、APK 批量分发、屏幕分享、USB Bridge、已装应用管理、PDA 外设兼容（扫描头广播监听、蓝牙打印机 ESC/POS） |
| ESB 企业服务总线 / 系统集成 | 出站连接器（HTTP/MQTT/Kafka/WebSocket）、数据栈（外部库连接/Buffer/开放 API）、第三方 SSO（OAuth2/OIDC） |
| 多屏联动工作流 | SCADA 组态编辑器 + 事件引擎、DAG 工作流编排、设备事件 + 系统事件统一总线、跨屏联动控制 |
| Form App（PDA 低码平台） | 专为 小屏手持终端 定制的低代码表单设计器、运行时渲染、扫码联动、草稿暂存、下发到设备 Agent |
| 工单系统 + 双向对接 | 工单全生命周期、状态流转工作流、自定义触发器（扫码/广播/HTTP/定时）、双向同步外部工单系统（ERP/MES/钉钉等） |
| 远程桌面 / 屏幕分享 | 低延迟实时画面、触控回传、免登录分享链接、摄像头 WebRTC、远程协助 |
| 设备维修工单 / 巡检工单 | 工单关联设备/设备组、现场扫码定位、设备快照、图片附件、时间线追踪 |
| 工业组态 / 可视化大屏 | SCADA 编辑器、ECharts 图表、容器组件、数据点实时刷新、发布分享 |
| 第三方 SSO / OAuth2 认证 | OIDC/OAuth2 单点登录、用户自动同步、角色映射、审计日志 |
| 数据采集 / 开放 API | 自定义事件 + 出站连接器、数据栈开放接口、API Key + 权限范围（scope）、MCP 工具集 |
| MDM 轻量替代 | 自托管、开放 API、审计日志；非系统级管控，侧重现场协同与运维 |
适合需要 Android 设备运维 + 系统集成 + 现场工单管理 + 移动端协同作业 的团队，包括设备维修、巡检巡查、仓储物流、门店运营等场景；数据留在自己服务器，可配合 Makefile / Docker 一键构建与部署。
平台围绕 五大核心能力 构建完整的企业现场数字化方案。下表按域给出成熟度与核心能力，便于快速判断是否覆盖你的需求（成熟度仅作参考，详见 docs/plan.md）。
| 能力域 | 成熟度 | 核心能力 |
|---|---|---|
| 1. Android 设备管理 | ✅ 生产可用 | 设备/分组台账、远程画面 + 触控、Web Shell / Logcat、APK 分发与远程安装、ADB 操作、截图/录屏/录音、文件管理、摄像头 WebRTC、屏幕分享链接、审计日志、USB Bridge、已装应用管理、PDA 外设兼容（扫描头、蓝牙打印机） |
| 2. ESB 系统对接 + 第三方 SSO | ✅ 生产可用 | 出站连接器（HTTP/MQTT/Kafka/WebSocket/STOMP/Cron）、阶段式流水线、静态/动态鉴权、环回防护、投递日志、数据栈（MySQL/SQLite 外部库连接、Buffer Webhook/HTTP Poll 入站、开放数据 API）、第三方 SSO（OAuth2/OIDC 单点登录、用户同步、角色映射） |
| 3. 多屏联动工作流 | 🟢 功能完整 | SCADA 编辑器（拖拽画布、图层/对齐/复制粘贴、12 种 ECharts 图表、容器组件、报警灯、数据点绑定实时刷新、动画与事件引擎、发布预览/分享）、DAG 工作流编排（节点配置、条件分支、并行执行、子流程嵌套）、统一事件总线（设备事件 + 系统事件 + 外部事件）、跨屏联动控制 |
| 4. Form App（PDA 低码平台） | 🟢 功能完整 | 专为小屏手持终端定制：表→页面快速生成、多页面设计器、运行时渲染、条件渲染/级联查询/草稿、下发到设备 Agent、扫码联动（兼容 PDA 扫描头）、页面级事件与蓝牙打印机集成、Android 9 兼容性优化 |
| 5. 实时工单系统 + 双向对接 | ✅ 生产可用 | 工单类型配置、状态流转与工作流、标签管理、QR 码关联（设备/业务单号/其他编码）、设备快照、实时看板（STOMP 推送）、时间线追踪、图片附件、批量归档、Web + 移动端处理、自定义触发器（扫码/广播/HTTP Webhook/定时）、双向同步外部工单系统（通过出站连接器对接 ERP/MES/钉钉等） |
| Android Agent | ✅ 生产可用 | WebSocket 长连接、屏幕推流、命令分发、自定义事件采集、MQTT 转发、Agent 菜单目录、Form App WebView + 扫码、工单列表与详情、PDA 外设支持（扫描头广播监听、蓝牙打印机 ESC/POS 指令） |
| AI 扩展能力 | 🔬 实验性 | Form App AI 创建（自然语言描述 → 表单页面生成）、ESB 接入 AI 解析（三方 API 文档 → 自动生成连接器配置）、工作流 AI 优化（分析历史执行 → 优化节点配置与分支逻辑） |
| 开放 API / MCP | 🟡 基础设施 | API Key + 权限范围（scope）、/api/open/v1/* 开放接口、/mcp/v1/ MCP 工具集，便于接入 CI / 内部系统 / AI 助手 |
| 核心处理机制 | ✅ 生产可用 | 标准化 Schema 体系：入参 Schema（参数校验 + 类型转换 + 默认值）、返回结果 Schema（结构规范 + 错误码统一）、全局参数（租户隔离、用户上下文、追踪 ID）、Schema 注册与校对机制（schema/ 目录统一管理三端契约） |
| 部署与扩展 | ✅ 单机成熟 | Makefile 跨平台编译与 release 打包、Docker / docker-compose、API 限流；多实例 + Redis 中继与 Prometheus 指标（见 docs/horizontal-scaling.md） |
边界说明：本平台侧重现场协同与运维协作 + 系统集成，非系统级 MDM 管控（不做强制策略、远程擦除等系统级管理）；工单系统面向中小规模现场作业（百级并发），Form App 专为 PDA / 小屏手持终端 优化，超大规模工业 SCADA 或 FSM 请评估专用方案。AI 扩展能力通过 MCP 接口与 Claude / ChatGPT 等 AI 助手集成，提升配置效率。核心处理机制通过标准化 Schema 保证前后端、移动端的接口一致性与类型安全。
下面按「想解决的问题」给出可落地的组合方式，帮助你判断如何使用：
- 诉求：设备维修、巡检、报障等现场作业需要工单系统管理全流程，移动端可快速接单、扫码定位、拍照上传、填写处理结果。
- 怎么用：Web 端配置 工单类型与工作流 → 创建工单并分配 → 移动端 Agent 工单列表 查看待处理任务 → 扫码关联设备/业务单号 → 拍照附件 + 填写处理记录 → 状态流转 → Web 端实时看板监控 + 时间线追踪。
- 涉及能力：工单系统、Android Agent 工单模块、标签管理、设备快照、实时看板（STOMP）。
- 诉求：设备出故障或定期巡检时需要工单记录，关联具体设备，现场人员扫码即可查看设备信息与历史工单。
- 怎么用：工单创建时 关联设备或设备组 → 移动端扫设备 QR 码自动匹配工单 → 查看 设备快照（名称/别名/分组） → 如需远程协助可跳转 远程画面 → 处理完成后归档，Web 端可按设备查询历史工单。
- 涉及能力：工单系统、设备台账、QR 码关联、设备快照、远程画面（可选）。
- 诉求：仓储、门店、产线有几十到上百台扫码枪 / 工业 PDA，需要统一看在线状态、批量装更新、远程排障。
- 怎么用：设备端装 Agent → Web 控制台统一台账与分组 → 批量安装/卸载 APK → 出问题时 远程画面 + 触控 + Shell/Logcat 排查 → 截图/录屏归档留证。
- 涉及能力：设备运维、Android Agent、应用分发、终端日志。
- 诉求：远程查看某台设备实时画面、协助操作，或向他人演示而不暴露后台账号。
- 怎么用：屏幕实时查看 + 触控回传；对外只需生成 免登录分享链接，按权限限定可见范围（适合协助、演示、监考）。
- 涉及能力：远程画面、屏幕分享、摄像头 WebRTC。
- 诉求：PDA 扫码 / 系统广播等事件要实时推送到 ERP / MES / 企业微信等外部系统。
- 怎么用：在 自定义事件 中配置广播监听 → 通过 出站连接器 的阶段式流水线推送（支持 HTTP、MQTT/Kafka、动态鉴权 Token、投递日志重试）；也可 MQTT 直转。
- 涉及能力：自定义事件、出站集成、Agent MQTT 转发。
- 诉求：把数据库或设备上报的数据做成实时刷新的看板 / 组态画面。
- 怎么用：数据栈 连接外部库并定义数据接口（或用 Buffer 接收 Webhook/轮询入站）→ 组态 SCADA 拖拽画布绑定数据点 → 发布后通过分享链接投屏展示，数据经 STOMP 实时推送。
- 涉及能力：数据栈、组态 SCADA、开放 API。
- 诉求：现场人员需要在 PDA 上填报 / 扫码录入，使用扫描头快速输入、蓝牙打印机打印标签，且表单要能快速迭代、免重新打包。
- 怎么用：Form App 设计器快速从数据表生成多页面表单 → 一键 下发到设备 Agent 的菜单 → Agent 内置 WebView 运行，支持 PDA 扫描头联动（监听广播自动填充字段）、蓝牙打印机（ESC/POS 指令打印标签/小票）、级联查询、草稿暂存。
- 涉及能力：Form App、Agent 菜单、PDA 外设集成、数据栈。
- 诉求：快速创建表单页面、对接复杂三方 API、优化工作流配置，降低技术门槛。
- 怎么用：
- Form App AI 创建：自然语言描述需求（"创建设备巡检表单，包含设备编号、巡检项、照片上传"）→ AI 自动生成表单页面配置
- ESB 接入 AI 解析：提供三方系统 API 文档或 Swagger URL → AI 自动解析并生成出站连接器配置（鉴权、参数映射、错误处理）
- 工作流 AI 优化：分析历史执行日志与性能指标 → AI 建议优化节点配置、简化分支逻辑、调整超时策略
- 涉及能力：MCP 工具集、Form App 设计器、出站连接器、DAG 工作流引擎。
- 诉求：用脚本或第三方系统调用平台能力，或让 AI 助手直接操作组态/设备数据。
- 怎么用：签发带 权限范围（scope） 的 API Key → 调用
/api/open/v1/*开放接口；或通过/mcp/v1/MCP 工具集 让兼容 MCP 的客户端（Claude Desktop、Cline、Continue 等）调用。 - 涉及能力：开放 API、MCP。
工单管理 — 工单类型筛选、状态看板、QR 码关联、标签分类、实时更新。
设备详情 — Agent 在线、网络与存储、PDA / 终端 快捷入口（远程画面、Shell、截图、测速等）。
屏幕查看（Android 远程桌面） — 实时画面、端到端延迟、分享链接 与投屏状态。
- Go 1.21+
- Node.js 18+（仅在你需要重新构建前端时）
- adb（Android 平台工具，在
PATH中或配置里写绝对路径） - ffmpeg（可选；需要服务端把录屏合成 MP4 时再装，否则可留空）
请在仓库根目录（与 web/、server/ 同级）执行下列命令，这样静态页面路径 ./web/dist 才能正确加载。
也可使用 make all 构建前端并编译服务端二进制（见仓库根目录 Makefile）；若要同时启用 组态 SCADA 与 Form App，请用 make server（会一并构建 scada-editor/ 与 form-app/）。
cd web && npm install && npm run build && cd ..go build -C server -o app-manager .
./app-manager server/config.sqlite.yaml启动后浏览器访问：http://127.0.0.1:8080
首次启动若无用户，会自动创建管理员：
- 用户名：
admin - 密码：
admin123
务必登录后修改密码；生产环境请修改 jwt.secret 或设置环境变量 JWT_SECRET。
仓库已内置多阶段 Dockerfile 与 compose 文件，免本机装 Go / Node：
# 默认 SQLite 单容器
export JWT_SECRET=$(openssl rand -hex 32)
docker compose up -d --build
# 访问 http://localhost:8080（默认账号 admin / admin123）需要 MySQL 时改用 docker-compose.mysql.yml：
docker compose -f docker-compose.mysql.yml up -d --build数据与上传分别挂载到 app-data / app-uploads 卷，容器重启不丢失。
| 文件 | 用途 |
|---|---|
| server/config.sqlite.yaml | 简化配置：SQLite，复制即用 |
| server/config.yaml | 示例（含 MySQL 等），可按需参考 |
指定配置文件：
./app-manager /path/to/your-config.yaml常用环境变量（覆盖配置中的同名项）：
JWT_SECRET— JWT 密钥ADB_PATH— adb 可执行文件路径FFMPEG_PATH— ffmpeg 可执行文件路径
自定义事件支持转发到 MQTT broker，在配置文件中启用：
mqtt:
enabled: true
broker: tcp://localhost:1883
username: ""
password: ""
client_id: app-manager
qos: 1在「自定义事件配置」页面可为事件分组或单个事件定义配置 MQTT 主题，事件上报时自动转发。
将 database 改为例如：
database:
type: mysql
dsn: "user:pass@tcp(127.0.0.1:3306)/app_manager?charset=utf8mb4&parseTime=True&loc=Local"设备端（PDA、手机、工业平板 等）需安装配套 Agent，配置服务器地址后与控制台保持 WebSocket 长连接，即可使用 远程画面、Shell、日志 等能力。
仓库内可用 Gradle 或 Makefile 编译安装，例如：
make install-agent
# 或
cd agent && ./gradlew :app:installDebug亦可使用脚本 ./scripts/sync-agent-apk.sh（需本机 Android SDK / Gradle；环境变量可参考 scripts/sync-agent-apk.env.example）。
后端仍按上文在仓库根目录启动；前端单独调试时：
cd web && npm install && npm run devVite 默认把 /api、/ws 代理到 http://127.0.0.1:8080，如需改端口可设置环境变量 VITE_PROXY_TARGET。
server/ Go 服务（API、WebSocket、任务队列、数据栈、出站、MCP）
web/ Vue 3 主控制台
scada-editor/ 组态编辑器（React 独立子应用，由 Go 服务托管）
form-app/ 低代码表单设计器 + 运行时（React，Go 托管）
agent/ Android Agent 工程
bridge/ 本地 USB 扫描桥接（Go）
schema/ 三端共享 TypeScript Schema 定义（入参 Schema、返回结果 Schema、全局参数、接口契约）
├── data-interface/ 数据接口 Schema（开放 API 入参/返回定义）
├── scada/ 组态编辑器组件 Schema（画布元素、容器、图表配置）
├── form-app/ Form App 页面 Schema（组件配置、事件定义、运行时契约）
└── reconcile/ Schema 校对工具（检查前后端 Schema 一致性）
scripts/ 辅助脚本（如 APK 同步）
docs/ 文档与界面截图（README 引用）；整体规划见 docs/plan.md
Makefile 构建 server / web / scada-editor / form-app / agent 与 release 打包
想了解完整能力栈、成熟度与路线图，参见
docs/plan.md（平台全景计划）。schema/ 目录通过 TypeScript 定义统一的接口契约，保证 Go 后端、Vue/React 前端、Android Agent 三端的类型安全与接口一致性。
平台正在向 统一事件驱动架构 演进，目标是通过 DAG 工作流引擎 统一全局事件流标准，实现后端各类工作流的统一编排与执行。
统一工作流引擎 (DAG Workflow Engine)
将现有分散的工作流系统（工单工作流、出站连接器工作流、数据轮询工作流等）统一到一个基于 有向无环图 (DAG) 的工作流引擎上：
- 统一编排模型：所有工作流统一使用 DAG 节点 + 边的声明式配置
- 可视化编辑器：拖拽式 DAG 编辑器，支持节点配置、条件分支、并行执行、子流程嵌套
- 执行引擎：调度器 + 执行器分离，支持节点重试、超时控制、错误处理、状态持久化
- 监控与追踪：完整的执行日志、性能指标、可视化执行路径追踪
统一事件系统 (Unified Event System)
建立全局标准事件总线，连接平台各个子系统：
- 事件标准化：统一事件模型（事件类型、载荷结构、元数据规范）
- 事件路由：基于事件类型和规则的智能路由，支持事件过滤、转换、聚合
- 订阅机制：多订阅者模式，支持优先级、顺序保证、At-Least-Once 语义
- 跨系统集成：设备事件、工单事件、系统事件、外部事件统一流转
应用场景整合
通过统一的 DAG 工作流引擎和事件系统，以下场景将获得统一的编排能力：
| 场景 | 当前实现 | 演进后 |
|---|---|---|
| 工单工作流 | 阶段式流水线（Webhook、HTTP、MQTT 等） | DAG 节点编排，支持复杂条件分支、并行审批、子流程 |
| 出站连接器 | 独立的 Connector 配置和执行器 | 统一为 DAG 工作流的一种触发器和动作节点 |
| 自定义事件 | 事件监听 + MQTT 转发 + 连接器 | 统一事件总线 + DAG 订阅节点，支持复杂事件处理 |
| 数据轮询 | Buffer HTTP Poll、Data Poll 分散实现 | DAG 调度节点 + Cron 触发器统一管理 |
| Form App 事件 | 页面级事件 + 前端 SDK | 事件上报到统一总线，后端 DAG 工作流响应 |
| SCADA 联动 | 组态事件引擎（前端） | 前后端事件桥接，支持后端 DAG 工作流联动控制 |
技术架构
参见 docs/event-system-evolution.md 了解完整的演进路线图与技术设计：
- 第 1 步：事件引擎脱离 Formily，建立独立的事件总线
- 第 2 步：AppState 统一状态管理，支持跨组件响应式状态
- 第 3 步：ToolRegistry 工具注册机制，支持动态工具加载和降级
- 第 4-8 步：DAG 调度器、执行器、可视化编辑器、迁移与兼容层
这一演进将大幅提升平台的 灵活性、可扩展性与可维护性，让复杂业务逻辑的编排更加直观和高效。
bridge/ 是一个轻量本地代理程序，运行在管理员电脑上，通过 WebSocket 向浏览器推送本机 USB 连接的 Android 设备列表，并支持一键注册到磐石服务器。
# 编译
cd bridge && go build -o bedrock-bridge .
# 运行（需本机已安装 adb 并在 PATH 中）
./bedrock-bridge
# 监听 ws://127.0.0.1:17175浏览器打开磐石控制台 → 设备列表页 → 点击「USB 扫描」，即可自动发现并注册 USB 设备。
Bridge 仅监听本地回环地址
127.0.0.1，不对外暴露。
欢迎 Issue / PR：优化文档（如 PDA 管理、远程桌面分享 等场景的说明）、修复问题、分享部署经验。
若在生产环境部署，请务必将默认密码、jwt.secret 与数据库连接信息替换为安全值。