# iaios

**Repository Path**: coolbacon/iaios

## Basic Information

- **Project Name**: iaios
- **Description**: 工业智能操作系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 工业AIOS (Industrial AIOS)

工业AIOS（Industrial AIOS，简称 IAIOS）原型。当前项目使用 Python + Reflex 构建控制台，用于探索工业应用在 Incus 容器/虚拟机上的统一部署、监控、调度、编排、镜像管理和故障迁移能力。

## 当前已经具备的能力

- PostgreSQL 连接式登录闸门，用于开发阶段验证数据库连通性。
- Reflex 控制台布局：左侧导航、顶部工具栏、主内容区、右侧状态栏。
- 静态系统总览大盘：CPU、内存、网络、性能趋势、系统时间和资源分配。
- 静态物理拓扑图：基于 React Flow 展示交换机、边缘服务器、NAS、工业网关和端口级连线。
- Web SSH 终端原型：浏览器 xterm.js 通过 WebSocket 桥接到后端 asyncssh PTY。
- 节点纳管表单 UI 原型。
- 物理节点 Agent 实验脚本：通过 HTTP 注册/bootstrap 与 fallback 心跳，正式遥测通道规划为 MQTT（HTTP 与 MQTT 端口长期并存、职责分离）。
- 中央镜像仓库第一版：支持本地 Incus 导出文件上传、控制服务器从互联网 Incus remote 拉取镜像、Nginx 3008 分发 artifacts、SSH 触发节点导入本地 Incus cache。

## 当前还没有完成的能力

- 正式数据库模型、ORM 和迁移系统。
- 真实用户、角色、权限、会话和操作审计。
- Incus API 管控层。
- 工业应用、应用实例、部署拓扑和调度模型。
- 真实监控数据入库和大盘查询。
- 高级镜像治理能力（签名、SBOM、安全扫描、GC、simplestreams remote）。
- 带状态迁移、热备和故障自愈闭环。

## 目录结构

```text
iaios/
  iaios.py                 # Reflex 应用入口与页面路由
  api/                    # WebSocket / API 入口
  components/             # Reflex UI 组件与少量 JS 包装组件
  core/                   # 配置等横切能力
  integrations/           # SSH、未来 Incus/MQTT 等外部系统集成
  models/                 # 预留：数据库/领域模型
  repositories/           # 预留：数据库访问层
  services/               # 业务服务层
  states/                 # Reflex State，只负责页面状态和事件转发
client/
  physical-node/          # 边缘节点 Agent 实验脚本
docs/                     # 需求、数据库设计与评审文档
tools/                    # 临时工具脚本
```

## 运行方式

项目要求 Python 3.12：

```bash
uv sync --locked
uv run python main.py
```

`main.py` 会在启动前检查前端/后端默认端口 `3000/8000`。如果旧 IAIOS 进程仍占用端口，它会直接退出并显示监听者，不允许 Reflex 自动漂移到 `3001/8001`，避免浏览器与固定回连 `8000` 的物理 Agent 连接不同后端。生产模式使用：

```bash
uv run python main.py --env prod
```

项目依赖统一由 `uv` 管理，`uv.lock` 必须提交并保持一致。

边缘节点 Agent 实验依赖是可选依赖：

```bash
uv sync --locked --extra agent
```

## 配置项

运行配置集中在 [iaios/core/config.py](iaios/core/config.py)。当前为了保持演示可用，保留了部分 demo 默认值。可以用环境变量覆盖：

| 环境变量 | 用途 |
| --- | --- |
| `IAIOS_DB_HOST` | 登录页默认 PostgreSQL 主机 |
| `IAIOS_DB_PORT` | 登录页默认 PostgreSQL 端口 |
| `IAIOS_DB_NAME` | 登录页默认 PostgreSQL 数据库名 |
| `IAIOS_DB_USER` | 登录页默认 PostgreSQL 用户名 |
| `IAIOS_WS_BASE_URL` | 前端连接终端 WebSocket 的 base URL |
| `IAIOS_TIMEZONE` | 控制台系统时间显示时区（IANA 名称，如 `Asia/Shanghai`；为空则使用服务器 OS 时区） |
| `IAIOS_SERVER_URL` | Agent 回连控制台 HTTP API 的地址，用于注册/bootstrap 与 HTTP fallback 心跳 |
| `IAIOS_MQTT_HOST` | MQTT Broker 主机（后续正式遥测通道） |
| `IAIOS_MQTT_PORT` | MQTT Broker 端口，默认 3009（1883 已被现场其它系统占用，IAIOS 端口从 3008 后顺延） |
| `IAIOS_IMAGE_REPO_ROOT` | IAIOS 中央镜像库本地文件根目录，默认 `/var/lib/iaios/image-repo` |
| `IAIOS_IMAGE_DOWNLOAD_BASE_URL` | 节点下载镜像 artifacts 的 Nginx 地址，必须是从节点可访问的控制服务器地址；未显式设置时会优先由 `IAIOS_SERVER_URL` 推导为同主机 `:3008`，否则尝试使用本机 LAN IP |
| `IAIOS_IMAGE_DOWNLOAD_PORT` | 中央镜像库 Nginx 文件服务端口，默认 3008；现场防火墙已开放 `3008:3012/tcp` 作为 IAIOS 预留段 |
| `IAIOS_IMAGE_NGINX_ACCEL` | 镜像下载是否使用 Nginx `X-Accel-Redirect`，默认 true |
| 控制服务器 `incus` CLI | “从官方仓库拉取”功能依赖本机 `incus image copy/export/delete`；需能访问 `images:` 等互联网 remote |
| `/var/lib/iaios/image-repo` | 逻辑镜像库目录；当前开发部署建议手动 bind mount 到 `/home/iaios-image-repo` 以使用 `/home` 的大容量空间 |
| `IAIOS_DEMO_SSH_HOST` | demo 终端 SSH 目标主机 |
| `IAIOS_DEMO_SSH_PORT` | demo 终端 SSH 目标端口 |
| `IAIOS_DEMO_SSH_USER` | demo 终端 SSH 用户 |
| `IAIOS_DEMO_SSH_PASSWORD` | demo 终端 SSH 密码 |

> 注意：`IAIOS_DEMO_SSH_*` 只是为了保持当前 Web SSH 终端演示功能。生产版本应改为从数据库读取节点和加密凭据，并在打开终端前做权限校验和操作审计。

## 架构约定

后续开发尽量遵守以下边界：

- `components/` 只写 UI 组合。
- `states/` 只维护页面状态和响应用户事件。
- `services/` 写业务逻辑，例如拓扑查询、终端目标解析、节点纳管、调度编排。
- `repositories/` 写数据库访问。
- `integrations/` 写外部系统适配，例如 SSH、Incus、MQTT、镜像仓库。
- 高危操作必须经过 service 层，后续要加入权限检查、参数校验、执行、审计记录。

## 数据库设计状态

数据库设计文档集中在 `docs/`：

- [docs/require.md](docs/require.md)：需求基线。
- [docs/iaios_database_design.md](docs/iaios_database_design.md)：当前数据库设计讨论稿，覆盖 IAM、凭据、资产、Incus、镜像、存储、拓扑、应用、调度、监控、HA 和审计等领域。
- [docs/iaios_database_design.sql](docs/iaios_database_design.sql) 与 [docs/iaios_database_design.xml](docs/iaios_database_design.xml)：早期 25 表基线 SQL/模型，作为历史参考。
- [docs/iaios_code_review_and_improvement_plan.md](docs/iaios_code_review_and_improvement_plan.md)：代码评审与改进计划。

### 数据库初始化（阶段一 MVP 已落地）

阶段一 MVP 已按设计文档实现：SQLAlchemy 2.x 模型（[iaios/models/](iaios/models/)）+ Alembic 迁移（[alembic/](alembic/)）+ seed 脚本（[iaios/seed.py](iaios/seed.py)）。覆盖 IAM、凭据、物理资产、阶段一拓扑（LLDP+Agent+手工）与审计，共 25 张表。

准备环境变量（至少数据库连接 + 加密主密钥）：

```bash
# 生成一个 Fernet 主密钥（务必妥善保存，不要提交到 Git）
export IAIOS_SECRET_KEY=$(python -c "from cryptography.fernet import Fernet;print(Fernet.generate_key().decode())")
export IAIOS_DB_HOST=10.176.165.1 IAIOS_DB_PORT=5432 IAIOS_DB_NAME=iaios
export IAIOS_DB_USER=iaios_admin IAIOS_DB_PASSWORD=******
# 或直接给完整 DSN：export IAIOS_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db
```

控制面的表建在独立 schema `iaios`（owner 为应用角色），因此应用角色只需对数据库有 CREATE 权限、无需超级用户，也避开 PostgreSQL 15+ 对 `public` 的限制。首次需执行一次 schema 初始化：

```bash
# 一次性：创建 iaios schema 并把它设为该角色默认 search_path
PGPASSWORD=$IAIOS_DB_PASSWORD psql -h "$IAIOS_DB_HOST" -U "$IAIOS_DB_USER" -d "$IAIOS_DB_NAME" -f tools/db_setup.sql
```

然后迁移、灌入初始数据：

```bash
uv run alembic upgrade head      # 建表（gen_random_uuid 为 PG13+ 内置，无需 pgcrypto）
uv run python -m iaios.seed       # 创建默认项目、admin 用户、加密密钥元数据、默认系统设置
```

`seed` 是幂等的，可重复执行；若未设置 `IAIOS_ADMIN_PASSWORD`，会随机生成并打印一次 admin 密码。后续修改模型后用 `uv run alembic revision --autogenerate -m "..."` 生成增量迁移（TimescaleDB 专有 DDL 需手写，见设计文档 14.2）。