Ithiltir Dash 是单实例应用。根入口只启动一个 HTTP 进程，该进程装配 API、SPA、主题资源、安装脚本、节点资产分发和后台服务。
运行边界
| 组件 | 责任 |
|---|
cmd/dash | 进程入口、配置加载、依赖装配、迁移入口和关闭流程 |
| HTTP 服务 | 挂载 /api、/theme、/deploy 和 SPA |
| PostgreSQL + TimescaleDB | 持久化指标历史、流量事实、节点元数据、告警规则、告警通知 outbox 和系统设置 |
| Redis | 默认保存会话、热点快照和告警运行时状态 |
| 进程内内存 | 节点鉴权索引和易失 Agent 更新请求；--no-redis 时承接会话和热点运行时状态 |
| Ithiltir-node | 上报指标和静态主机信息；Windows runner 启动时接收更新 manifest |
| Web UI | 读取看板数据并提交管理操作 |
HTTP 面
| 前缀 | 作用 |
|---|
/api/auth | 登录、续期、登出、会话撤销 |
/api/version | Dash 版本和打包携带的节点版本 |
/api/front | 看板读取 |
/api/metrics | 历史指标和在线率查询 |
/api/statistics | 统计访问策略和流量统计查询 |
/api/node | 节点上报和节点身份读取 |
/api/admin | 管理台写操作 |
/theme | 当前主题 CSS、主题 manifest 和预览图 |
/deploy | 安装脚本和节点发布资产 |
/ | SPA |
数据流
- Ithiltir-node 通过
/api/node/* 上报指标和静态主机信息。
- 指标上报成功响应可以包含更新 manifest。
- PostgreSQL + TimescaleDB 保存持久化历史、流量事实、配置和告警通知 outbox。
- Redis 或进程内内存保存热点快照、会话和告警运行时状态。
- 后台服务评估告警、发送队列通知并汇总流量数据。
状态和保留策略
- 默认启动依赖 PostgreSQL 和 Redis。
--no-redis 会把 Redis 承载的运行时状态改用进程内内存。- 节点鉴权和待下发 Agent 更新请求使用进程内内存，不走 Redis。
- 告警评估读取热点快照。内置离线和 RAID 规则来自快照新鲜度和上报 RAID 健康状态。
- 告警服务启动后 1 分钟内不会新开告警事件。
- 告警通知 payload 存入 PostgreSQL outbox，并由带租约的重试 worker 发送。
- 数据库历史保留默认
45 days；普通监控用 database.retention_days，流量 5 分钟事实表用 database.traffic_retention_days。
- 流量
lite 模式保存月度入/出总量和估算峰值；billing 模式额外维护 5 分钟事实、日汇总、P95、覆盖率和月度快照。
- 历史指标默认不对游客公开。
history_guest_access_mode=by_node 时，只对游客可见节点开放。
- 流量统计是否对游客公开由流量设置控制，并仍受节点可见性限制。
鉴权边界
| 区域 | 鉴权 |
|---|
/api/auth/login | 管理员密码 |
/api/auth/refresh、/api/auth/logout | refresh cookie + X-CSRF-Token |
/api/front/*、/api/metrics/*、/api/statistics/* | Bearer 可选；匿名请求按系统可见性设置过滤 |
/api/node/* | X-Node-Secret |
/api/admin/* | Authorization: Bearer <access_token> |
前端和反向代理
前端和后端必须保持同源路径。生产反向代理应把 /api、/theme、/deploy 转给 Dash 后端，/ 保持为 Dash SPA。app.public_url 必须是根路径 URL，不支持 /dash 这类路径前缀。