OpenViking Console: Capability Rollout Plan and Detailed Solution Overview

[zhoujh01]

#383

1. 背景与目标

• 为 OpenViking 提供一个可独立启动的 Console 示例，降低调试、演示和运维操作门槛。
• 将核心能力（文件、检索、资源入库、多租户、监控）统一到可视化入口，提升操作效率。
• 在保证易用性的同时，强化写操作安全护栏，降低误操作风险。

———

2. 方案概述（架构）

采用三层结构：

1. 前端控制台（静态页面）
2. Console BFF（FastAPI）
3. OpenViking 主服务

关键设计

• 前端统一调用 /console/api/v1/*。
• BFF 转发到 OpenViking /api/v1/*。
• 通过 BFF 实现：
  • 接口收敛
  • 统一错误格式
  • 写操作拦截
  • Header 白名单透传（如 X-API-Key）

———

3. 本次新增能力（重点）

3.1 文件系统能力（Filesystem）

• 支持 ls/tree/stat 浏览与元信息查看。
• 支持目录跳转、回退、上级、刷新、排序。
• 支持文件内容读取与资源详情查看。

3.2 检索能力（Find）

• 支持 query + target_uri 的检索请求。
• 结果表格化展示，支持动态列与排序。

3.3 资源入库能力（Add Resource）

• 支持“按路径入库”。
• 支持“先上传临时文件，再发起入库”。
• 支持参数：wait / strict / timeout / include / exclude / reason / instruction 等。

3.4 多租户管理能力（Tenants）

• 账户维度：创建、删除、列表、过滤、排序。
• 用户维度：新增、删除、角色变更、API Key 重置。
• 账户与用户联动展示，形成完整操作闭环。

3.5 监控能力（Monitor）

• 支持查看 system status。
• 支持查看 observer(system) 组件状态。

3.6 会话与鉴权能力（Settings）

• 支持页面设置 X-API-Key（存储于 session storage）。
• 所有请求自动携带 key，便于连续调试与演示。

———

4. 安全与风险控制设计

4.1 写操作总开关

• 默认只读。
• 仅在启动参数显式开启 --write-enabled 后允许写操作。

4.2 前后端双重防护

• 后端：写接口统一校验 write_enabled。
• 前端：基于 runtime capabilities 自动禁用写按钮。

4.3 高风险操作二次确认

• 多租户删除/变更等危险操作要求输入确认文本，降低误触风险。

4.4 最小化透传原则

• 仅透传必要 Header，避免无关敏感信息穿透。

———

5. 交付价值

• 研发价值：统一可视化调试入口，减少手工 API 调用成本。
• 运维价值：账户/用户管理与状态排查可在单页面完成。
• 演示价值：覆盖“浏览 → 检索 → 入库 → 管理 → 监控”的完整链路。
• 治理价值：默认只读 + 显式写开关 + 二次确认，兼顾效率与安全。

———

6. 当前边界与限制

• 当前位于 examples/，定位示例服务，尚未接入正式发布/CLI 主链路。
• 鉴权以 X-API-Key 为主，细粒度权限策略仍可增强。
• 自动化测试矩阵仍需完善（BFF 代理层与关键前端交互场景）。

———

7. 下一步建议

1. 产品化接入：评估从 example 向正式控制台模块演进。
2. 安全增强：补充审计日志、操作人追踪、可配置确认策略。
3. 可观测增强：扩展 observer 维度与失败请求诊断信息。
4. 测试补强：补齐 BFF 路由单测 + 关键 E2E UI 用例。
5. 体验优化：权限感知 UI、批量操作、更细粒度筛选。

———

1. Background & Goals

• Provide a standalone OpenViking Console example to reduce friction for debugging, demos, and operations.
• Consolidate core capabilities (filesystem, search, resource ingestion, multi-tenant management, monitoring) into one
  visual entry point.
• Improve usability while enforcing strong safeguards for write operations.

———

2. Solution Overview (Architecture)

Three-layer design:

1. Console Frontend (static UI)
2. Console BFF (FastAPI)
3. OpenViking upstream service

Key Design Choices

• Frontend calls only /console/api/v1/*.
• BFF proxies requests to OpenViking /api/v1/*.
• BFF centralizes:
  • API surface normalization
  • error handling
  • write access control
  • header allowlist forwarding (e.g., X-API-Key)

———

3. Capabilities Delivered (Highlights)

3.1 Filesystem Capabilities

• Supports ls/tree/stat browsing and metadata inspection.
• Supports navigation actions: go to path, back, up, refresh, sorting.
• Supports file content read and detail inspection.

3.2 Search Capabilities (Find)

• Supports semantic find with query + target_uri.
• Results are rendered in sortable tabular form with dynamic columns.

3.3 Resource Ingestion Capabilities (Add Resource)

• Supports “ingest by path”.
• Supports “temp upload, then ingest”.
• Supports advanced options: wait / strict / timeout / include / exclude / reason / instruction.

3.4 Multi-Tenant Management Capabilities (Tenants)

• Account-level: create, delete, list, filter, sort.
• User-level: add, remove, role update, API key reset.
• Linked account-user workflow provides a full operational loop.

3.5 Monitoring Capabilities (Monitor)

• Supports viewing system status.
• Supports viewing observer(system) component status.

3.6 Session & Auth Capabilities (Settings)

• Supports setting X-API-Key in UI (stored in session storage).
• Automatically attaches the key to all API requests.

———

4. Safety & Risk Control Design

4.1 Global Write Switch

• Default mode is read-only.
• Write operations are enabled only when started with --write-enabled.

4.2 Dual-Layer Protection

• Backend: all write routes enforce write_enabled.
• Frontend: write controls are auto-disabled based on runtime capabilities.

4.3 Confirmation for Dangerous Actions

• Sensitive tenant actions require typed confirmation to reduce accidental operations.

4.4 Minimal Forwarding Principle

• Only required headers are forwarded to minimize exposure risk.

———

5. Business/Engineering Value

• Engineering: unified visual console reduces manual API-call overhead.
• Operations: account/user administration and health checks in one page.
• Demo Enablement: complete end-to-end story (browse → search → ingest → manage → monitor).
• Governance: read-only default + explicit write enable + confirmation gates.

———

6. Current Scope Boundaries

• Implemented under examples/, as a standalone example service (not yet part of release/CLI mainline).
• Auth currently centers on X-API-Key; finer-grained enterprise RBAC can be extended.
• Automated test coverage still needs expansion (BFF routes + key UI flows).

———

7. Recommended Next Steps

1. Productization: evaluate promotion from example to official console module.
2. Security hardening: add audit logs, operator traceability, configurable confirmation policies.
3. Observability expansion: extend observer dimensions and failure diagnostics.
4. Test reinforcement: add BFF route unit tests and critical E2E UI scenarios.
5. UX refinement: permission-aware UI, batch operations, deeper filters.

———