secubox-openwrt/docs-zh/admin-control-center/API-REFERENCE.md

SecuBox 管理控制中心 - API 参考

语言: English | Francais | 中文

状态管理、组件注册表和控制中心功能的完整 API 参考。

---

目录

1. RPC 后端 API
   • 状态管理方法
   • 组件注册表方法
2. CLI 工具
   • secubox-state
   • secubox-component
   • secubox-sync-registry
3. JavaScript 前端 API
   • 状态管理
   • 组件管理
   • 实用函数
4. 状态工具
5. UI 组件
6. 数据结构

---

RPC 后端 API

所有 RPC 方法都通过 luci.secubox 对象暴露。

状态管理方法

get_component_state

获取组件的当前状态和元数据。

参数:

• component_id (string): 组件唯一标识符

返回:

{
  "component_id": "luci-app-auth-guardian",
  "current_state": "running",
  "previous_state": "starting",
  "state_changed_at": "2026-01-05T10:30:00Z",
  "error_details": {
    "type": "runtime_error",
    "message": "Service failed to start",
    "code": "E_SERVICE_START"
  },
  "history": [
    {
      "state": "starting",
      "timestamp": "2026-01-05T10:29:45Z",
      "reason": "user_action"
    }
  ],
  "metadata": {
    "installed_version": "1.0.0",
    "catalog_version": "1.0.1"
  }
}

示例:

L.resolveDefault(callGetComponentState('luci-app-auth-guardian'))
  .then(function(state) {
    console.log('Current state:', state.current_state);
  });

set_component_state

为组件设置新状态，支持原子转换验证。

参数:

• component_id (string): 组件唯一标识符
• new_state (string): 目标状态（参见状态定义）
• reason (string): 状态更改原因

返回:

{
  "success": true,
  "message": "State transition successful",
  "previous_state": "stopped",
  "new_state": "starting"
}

错误:

• 无效转换（返回 success: false）
• 组件未找到
• 状态已锁定

示例:

L.resolveDefault(callSetComponentState('luci-app-auth-guardian', 'starting', 'user_request'))
  .then(function(result) {
    if (result.success) {
      console.log('State changed successfully');
    }
  });

get_state_history

获取组件的状态转换历史。

参数:

• component_id (string): 组件唯一标识符
• limit (number, 可选): 最大历史记录条数（默认: 50）

返回:

{
  "history": [
    {
      "state": "running",
      "timestamp": "2026-01-05T10:30:00Z",
      "reason": "start_success",
      "metadata": {}
    },
    {
      "state": "starting",
      "timestamp": "2026-01-05T10:29:45Z",
      "reason": "user_action"
    }
  ]
}

示例:

L.resolveDefault(callGetStateHistory('luci-app-auth-guardian', 10))
  .then(function(result) {
    result.history.forEach(function(entry) {
      console.log(entry.state, entry.timestamp);
    });
  });

list_components

列出所有组件，支持可选过滤器。

参数:

• state_filter (string, 可选): 按状态过滤（如 "running", "error"）
• type_filter (string, 可选): 按类型过滤（如 "app", "module"）

返回:

{
  "components": [
    {
      "id": "luci-app-auth-guardian",
      "type": "app",
      "name": "Auth Guardian",
      "current_state": "running",
      "state_changed_at": "2026-01-05T10:30:00Z"
    }
  ]
}

示例:

// 获取所有运行中的应用
L.resolveDefault(callListComponents('running', 'app'))
  .then(function(result) {
    console.log('Running apps:', result.components.length);
  });

freeze_component

将组件标记为冻结（锁定状态，不允许转换）。

参数:

• component_id (string): 组件唯一标识符
• reason (string): 冻结原因

返回:

{
  "success": true,
  "message": "Component frozen successfully"
}

示例:

L.resolveDefault(callFreezeComponent('luci-app-firewall', 'system_critical'))
  .then(function(result) {
    console.log('Component frozen');
  });

clear_error_state

清除错误状态并将组件重置为最后一个已知的正常状态。

参数:

• component_id (string): 组件唯一标识符

返回:

{
  "success": true,
  "message": "Error state cleared",
  "new_state": "stopped"
}

示例:

L.resolveDefault(callClearErrorState('luci-app-vpn-client'))
  .then(function(result) {
    console.log('Error cleared, new state:', result.new_state);
  });

组件注册表方法

get_component

从注册表获取完整的组件元数据。

参数:

• component_id (string): 组件唯一标识符

返回:

{
  "id": "luci-app-auth-guardian",
  "type": "app",
  "name": "Auth Guardian",
  "packages": ["luci-app-auth-guardian", "nodogsplash"],
  "capabilities": ["authentication", "captive-portal"],
  "dependencies": {
    "required": ["luci-base"],
    "optional": ["uhttpd-mod-lua"]
  },
  "settings": {
    "enabled": true,
    "auto_start": true
  },
  "profiles": ["home-security", "enterprise"],
  "managed_services": ["nodogsplash"],
  "state_ref": "luci-app-auth-guardian"
}

get_component_tree

获取组件依赖树（递归）。

参数:

• component_id (string): 组件唯一标识符

返回:

{
  "component": {
    "id": "luci-app-auth-guardian",
    "name": "Auth Guardian",
    "type": "app"
  },
  "dependencies": {
    "required": [
      {
        "id": "luci-base",
        "name": "LuCI Base",
        "type": "module",
        "dependencies": {...}
      }
    ],
    "optional": []
  },
  "reverse_dependencies": [
    {
      "id": "profile-home-security",
      "type": "composite"
    }
  ]
}

update_component_settings

更新组件设置。

参数:

• component_id (string): 组件唯一标识符
• settings (object): 设置键值对

返回:

{
  "success": true,
  "updated_settings": {
    "enabled": true,
    "auto_start": false
  }
}

validate_component_state

验证组件状态与系统的一致性。

参数:

• component_id (string): 组件唯一标识符

返回:

{
  "valid": true,
  "inconsistencies": [],
  "recommendations": []
}

---

CLI 工具

secubox-state

状态管理命令行界面。

命令

get <component-id>

获取当前状态及元数据。

secubox-state get luci-app-auth-guardian

输出:

{
  "component_id": "luci-app-auth-guardian",
  "current_state": "running",
  "previous_state": "starting",
  "state_changed_at": "2026-01-05T10:30:00Z"
}

set <component-id> <state> [reason]

设置新状态，支持原子转换。

secubox-state set luci-app-auth-guardian starting user_request

输出:

Success: State transition: stopped -> starting

history <component-id> [limit]

查看状态历史。

secubox-state history luci-app-auth-guardian 10

list [--state=STATE] [--type=TYPE]

按状态/类型列出组件。

secubox-state list --state=running --type=app

validate <component-id>

验证状态一致性。

secubox-state validate luci-app-auth-guardian

sync

将状态数据库与实际系统状态同步。

secubox-state sync

freeze <component-id> <reason>

冻结组件（锁定状态）。

secubox-state freeze luci-app-firewall system_critical

clear-error <component-id>

清除错误状态。

secubox-state clear-error luci-app-vpn-client

secubox-component

组件注册表管理 CLI。

命令

list [--type=TYPE] [--state=STATE] [--profile=PROFILE]

带过滤器列出组件。

secubox-component list --type=app --state=running

get <component-id>

获取组件详情。

secubox-component get luci-app-auth-guardian

register <component-id> <type> [metadata-json]

注册新组件。

secubox-component register my-app app '{"name":"My App","packages":["my-app"]}'

组件类型:

• app - LuCI 应用
• module - opkg 包
• widget - 仪表盘小部件
• service - 系统服务
• composite - 组件组

unregister <component-id>

从注册表中移除组件。

secubox-component unregister my-app

tree <component-id>

显示依赖树。

secubox-component tree luci-app-auth-guardian

affected <component-id>

显示反向依赖。

secubox-component affected luci-base

set-setting <component-id> <key> <value>

更新组件设置。

secubox-component set-setting my-app enabled true

secubox-sync-registry

从目录自动填充组件注册表。

命令

sync

完整注册表同步（默认）。

secubox-sync-registry sync

apps

仅从目录同步应用。

secubox-sync-registry apps

plugins

仅从目录同步插件。

secubox-sync-registry plugins

packages

仅同步已安装的包。

secubox-sync-registry packages

---

JavaScript 前端 API

状态管理

api.getComponentState(component_id)

获取组件状态。

api.getComponentState('luci-app-auth-guardian')
  .then(function(state) {
    console.log('Current state:', state.current_state);
  });

api.setComponentState(component_id, new_state, reason)

设置组件状态。

api.setComponentState('luci-app-auth-guardian', 'starting', 'user_action')
  .then(function(result) {
    if (result.success) {
      console.log('State changed');
    }
  });

api.getStateHistory(component_id, limit)

获取状态历史。

api.getStateHistory('luci-app-auth-guardian', 10)
  .then(function(history) {
    history.forEach(function(entry) {
      console.log(entry.state, entry.timestamp);
    });
  });

api.listComponents(state_filter, type_filter)

列出组件。

api.listComponents('running', 'app')
  .then(function(components) {
    console.log('Running apps:', components);
  });

api.freezeComponent(component_id, reason)

冻结组件。

api.freezeComponent('luci-app-firewall', 'system_critical')
  .then(function(result) {
    console.log('Component frozen');
  });

api.clearErrorState(component_id)

清除错误状态。

api.clearErrorState('luci-app-vpn-client')
  .then(function(result) {
    console.log('Error cleared');
  });

组件管理

api.getComponent(component_id)

获取组件元数据。

api.getComponent('luci-app-auth-guardian')
  .then(function(component) {
    console.log('Component:', component.name);
  });

api.getComponentTree(component_id)

获取依赖树。

api.getComponentTree('luci-app-auth-guardian')
  .then(function(tree) {
    console.log('Dependencies:', tree.dependencies);
  });

api.updateComponentSettings(component_id, settings)

更新设置。

api.updateComponentSettings('luci-app-auth-guardian', {
  enabled: true,
  auto_start: false
}).then(function(result) {
  console.log('Settings updated');
});

增强方法

api.getComponentWithState(component_id)

一次调用获取组件及其状态。

api.getComponentWithState('luci-app-auth-guardian')
  .then(function(component) {
    console.log('Component:', component.name);
    console.log('State:', component.state_info.current_state);
  });

api.getAllComponentsWithStates(filters)

获取所有组件及其状态。

api.getAllComponentsWithStates({ state: 'running', type: 'app' })
  .then(function(components) {
    components.forEach(function(comp) {
      console.log(comp.name, comp.state_info.current_state);
    });
  });

api.bulkSetComponentState(component_ids, new_state, reason)

批量状态更改。

api.bulkSetComponentState(
  ['app1', 'app2', 'app3'],
  'stopped',
  'bulk_shutdown'
).then(function(results) {
  console.log('Bulk operation results:', results);
});

api.getStateStatistics()

获取状态分布统计。

api.getStateStatistics()
  .then(function(stats) {
    console.log('Total components:', stats.total);
    console.log('By state:', stats.by_state);
    console.log('By type:', stats.by_type);
  });

---

状态工具

state-utils.js 中的 JavaScript 工具。

方法

getStateConfig(state)

获取完整的状态配置。

var config = stateUtils.getStateConfig('running');
// 返回: { color: '#10b981', icon: '▶', label: 'Running', category: 'runtime', description: '...' }

getStateColor(state)

获取状态的 CSS 颜色。

var color = stateUtils.getStateColor('error');
// 返回: '#ef4444'

canTransition(fromState, toState)

验证状态转换。

var valid = stateUtils.canTransition('stopped', 'starting');
// 返回: true

getNextStates(currentState)

获取允许的下一个状态。

var nextStates = stateUtils.getNextStates('stopped');
// 返回: ['starting', 'disabled', 'uninstalling']

formatHistoryEntry(historyEntry)

格式化历史记录以供显示。

var formatted = stateUtils.formatHistoryEntry({
  state: 'running',
  timestamp: '2026-01-05T10:30:00Z',
  reason: 'user_action'
});
// 返回: "2026-01-05 10:30:00 - Running (User Action)"

getTimeAgo(timestamp)

获取相对时间字符串。

var timeAgo = stateUtils.getTimeAgo('2026-01-05T10:30:00Z');
// 返回: "5 minutes ago"

getStateStatistics(components)

计算状态分布。

var stats = stateUtils.getStateStatistics(components);
// 返回: { total: 25, by_state: {...}, by_category: {...} }

---

UI 组件

StateIndicator

渲染状态徽章和指示器。

render(state, options)

标准状态徽章。

var badge = StateIndicator.render('running', {
  showIcon: true,
  showLabel: true,
  showTooltip: true
});

renderCompact(state, options)

紧凑指示器（仅图标）。

var indicator = StateIndicator.renderCompact('error', {
  customTooltip: 'Critical error occurred'
});

renderPill(state, metadata, options)

完整详情药丸。

var pill = StateIndicator.renderPill('running', {
  timestamp: '2026-01-05T10:30:00Z'
}, {
  showDescription: true
});

renderDot(state, options)

最小点指示器。

var dot = StateIndicator.renderDot('running', {
  size: '0.75rem'
});

renderStatistics(statistics, options)

状态分布卡片。

var stats = StateIndicator.renderStatistics({
  by_state: { running: 10, stopped: 5, error: 2 }
});

StateTimeline

可视化状态历史。

render(history, options)

垂直时间线。

var timeline = StateTimeline.render(historyEntries, {
  limit: 20,
  showRelativeTime: true,
  showCategory: true
});

renderCompact(history, options)

内联紧凑时间线。

var compact = StateTimeline.renderCompact(historyEntries, {
  limit: 5
});

renderHorizontal(history, options)

水平时间线。

var horizontal = StateTimeline.renderHorizontal(historyEntries, {
  limit: 10
});

renderTransitionDiagram(currentState, options)

交互式转换图。

var diagram = StateTimeline.renderTransitionDiagram('stopped', {
  onTransitionClick: function(from, to) {
    console.log('Transition:', from, '->', to);
  }
});

---

数据结构

状态定义

状态	类别	描述	颜色
available	persistent	可供安装	#6b7280
installing	transient	安装进行中	#3b82f6
installed	persistent	已安装但未激活	#8b5cf6
configuring	transient	配置进行中	#3b82f6
configured	transient	配置完成	#8b5cf6
activating	transient	激活进行中	#3b82f6
active	persistent	激活但未运行	#06b6d4
starting	transient	服务正在启动	#3b82f6
running	runtime	服务正在运行	#10b981
stopping	transient	服务正在停止	#f59e0b
stopped	runtime	服务已停止	#6b7280
error	error	组件遇到错误	#ef4444
frozen	persistent	组件已冻结（锁定）	#06b6d4
disabled	persistent	组件已禁用	#9ca3af
uninstalling	transient	卸载进行中	#f59e0b

状态转换矩阵

available → [installing]
installing → [installed, error]
installed → [configuring, uninstalling]
configuring → [configured, error]
configured → [activating, disabled]
activating → [active, error]
active → [starting, disabled, frozen]
starting → [running, error]
running → [stopping, error, frozen]
stopping → [stopped, error]
stopped → [starting, disabled, uninstalling]
error → [available, installed, stopped]
frozen → [active]
disabled → [active, uninstalling]
uninstalling → [available, error]

组件元数据结构

{
  "id": "string",
  "type": "app|module|widget|service|composite",
  "name": "string",
  "packages": ["string"],
  "capabilities": ["string"],
  "dependencies": {
    "required": ["string"],
    "optional": ["string"]
  },
  "settings": {
    "key": "value"
  },
  "profiles": ["string"],
  "managed_services": ["string"],
  "state_ref": "string",
  "metadata": {
    "installed_version": "string",
    "catalog_version": "string",
    "auto_detected": boolean
  }
}

状态数据库结构

{
  "components": {
    "component-id": {
      "current_state": "string",
      "previous_state": "string",
      "state_changed_at": "ISO8601",
      "error_details": {
        "type": "string",
        "message": "string",
        "code": "string"
      },
      "history": [
        {
          "state": "string",
          "timestamp": "ISO8601",
          "reason": "string",
          "metadata": {}
        }
      ],
      "metadata": {}
    }
  },
  "version": "1.0",
  "last_updated": "ISO8601"
}

---

错误代码

状态管理错误

• E_INVALID_TRANSITION - 无效的状态转换
• E_COMPONENT_NOT_FOUND - 组件未找到
• E_STATE_LOCKED - 组件状态已锁定
• E_VALIDATION_FAILED - 状态验证失败

组件注册表错误

• E_COMPONENT_EXISTS - 组件已注册
• E_INVALID_TYPE - 无效的组件类型
• E_DEPENDENCY_MISSING - 未找到必需的依赖
• E_CIRCULAR_DEPENDENCY - 检测到循环依赖

---

性能考虑

• 状态转换使用文件锁定（flock）以确保原子性
• RPC 方法具有指数退避的重试逻辑
• 每个组件的状态历史限制为 100 条记录（可配置）
• 组件列表查询缓存 30 秒
• 批量操作使用 Promise.all 进行并行执行

---

安全考虑

• 状态转换需要适当的身份验证
• 冻结的组件需要管理员权限才能修改
• 系统关键组件有额外的保护措施
• 所有状态更改都会记录原因和时间戳

---

迁移和兼容性

• 现有 RPC 方法（get_appstore_apps 等）保持功能正常
• 状态感知方法是附加的，不是破坏性更改
• 没有状态条目的组件默认为 'available'
• 迁移脚本自动为现有组件初始化状态

---

另请参阅

• 架构文档
• 状态管理指南
• 组件系统指南
• 用户指南

---

版本: 1.0 最后更新: 2026-01-05 维护者: SecuBox 开发团队