# instrument-control-platform

**Repository Path**: sober1107/instrument-control-platform

## Basic Information

- **Project Name**: instrument-control-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-19
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 仪控软件安全管理平台

本目录是仪控平台的独立工作区。平台依据国家重点研发计划课题 4 任务书，提供跨业务可信身份、细粒度访问、仪控软件链上链下安全存储、安全事件溯源和协同完整性验证。前端、后端、构建产物和业务数据库均独立维护。

## 项目边界

- `frontend/ics-web`：仪控平台独立 Vue 前端，发布路径为 `/ics/`。
- `backend/platform-api`：仪控平台独立 Spring Boot 后端，Nginx 对外路径为 `/ics-api/`。
- `database`：仪控资产、事件和存证索引表；文件正文不存入 MySQL。
- `services/verkle-service`：仪控实例使用的 Verkle 服务源码。
- `contracts`：仪控实例合约。
- `deploy`：仪控实例独立部署配置。

AI Agent、安全状态和联邦学习不属于仪控平台。ICS 前端没有对应页面或导航，Nginx 对 `/ics-api/agent/` 和 `/ics-api/federated/` 明确返回 `404`。后端工作区保留少量共用底层兼容类，但它们不构成 ICS 对外接口，也不读取源平台业务数据。

## 与源平台的隔离

源平台位于同级目录 `../sgcc-trust-data-space`。两个项目可以复用 MySQL、Redis、IPFS、区块链和 Verkle 的技术基线，但运行数据必须隔离：

| 项目 | Web | API | MySQL | Redis | IPFS API | Verkle |
| --- | ---: | ---: | --- | ---: | ---: | ---: |
| 源平台（独立部署） | `/` | `/api/` | `sgcc_platform` | `0` | `5001` | `8011` |
| 仪控平台 | `/ics/` | `/ics-api/` | `ics_platform` | `6` | `5002` | `8021` |

不得从源平台目录构建仪控 jar，也不得把任一平台的前端 `dist` 复制到另一平台。

## 仪控业务闭环

1. 用户以 DID 登录，属性权威按仪控评测、运行日志、安全事件、索引结构、其他业务五个分片签发角色、组织和分片范围属性。
2. 用户可在“数据上链”直接选择文件，也可由外部系统按接口提交数据，无需先使用其他业务平台的桌面客户端。平台不预设提交内容是明文或密文，按实际收到的字节处理。
3. 聚合存证将收到的资料写入 ICS 独立 IPFS，将业务索引写入 MySQL，将 Verkle 证明写入 Redis DB 6，并把聚合根锚定到所属分片。软件包、配置、日志和敏感资料必须使用这种方式。
4. 原文上链仅允许公开、非敏感且不超过 16 KiB 的小文件；原文字节直接写入所属分片，提交前必须确认链上内容无法常规删除。
5. “数据读取”通过编号、索引键、文件名、摘要、方式和分片检索。聚合记录执行存证查验；原文记录可从账本读回并与本地原文逐字节摘要比对。
6. “聚合存证批量查验”逐条验证收到并保存的数据字节、IPFS 内容摘要、Verkle 聚合根和分片锚定状态。
7. “合约中心”支持源码输入和文件拖拽部署，列表展开后根据 ABI 动态生成函数参数并调用。管理中心权威可部署到所有分片，分片权威只能部署到所属分片，普通用户只能调用。
8. “安全事件溯源”通过可配置网关查询事件编号、资产编号、资源编号、漏洞编号或 SHA-256。联调期可使用本地兼容实现，生产环境切换到独立溯源服务；ICS 不直接连接溯源数据库或链节点。

平台只实现资料接收、存储、索引、查验和流转接口，不判断或强制上游采用哪种数据形态。调用方需要端侧加密时可提交密文包，需要提交普通业务文件时平台同样按接口处理；摘要与完整性验证始终以实际收到的字节为准。不得把口令、私钥或敏感正文提交到原文上链。

## 课题五系统集成接口

当前完整接口基线见 `docs/课题5 系统集成接口260330_v5.docx`。`v5` 合并了系统集成、仪控存证与查验、合约中心和事件适配接口；开发、联调和验收均以 v5 为准。系统间认证使用 HMAC-SHA256 挑战应答，不通过网络下发共享密钥；Bearer Token 默认有效 30 分钟，SSO 使用 60 秒一次性票据。

部署时必须设置 `ICS_INTEGRATION_SHARED_SECRET`，长度不少于 16 个字符。溯源接口验收后设置 `ICS_TRACE_PROVIDER=trace`、`ICS_TRACE_BASE_URL` 和 `ICS_TRACE_SERVICE_TOKEN`；详细边界见 `docs/溯源服务对接约定.md`。共享密钥和完整 Token 不得写入代码、Git 或日志。

## 任务书指标边界

任务书要求 8 节点共识出块时间不超过 200 ms、有效业务记录吞吐量不低于 10000 records/s、百万交易溯源查询不超过 500 ms。2026-09-18 五分片统一墙钟验收实测为 5000 笔物理交易、每笔覆盖 64 条业务记录、23.893 秒，物理交易 TPS 为 209.266，有效业务记录吞吐为 13393.044 records/s，提交与回执失败均为 0，峰值内存为 69.379%。同日 1500 笔短样本复测为 8944.377 records/s，未达到门槛，因此正式验收固定使用每分片 1000 笔以降低客户端启动偏差。该口径用于当前 ICS 吞吐验收；出块时延和百万级溯源仍应分别出具专项测试结果。

ICS 不提供 Paillier 受控计算、联邦学习、安全态势或 AI Agent 页面。这些能力属于源平台业务，不应出现在仪控操作流程中。

## 仿真资料初始化

首页的分片在线状态来自链路读探针，不能靠手工写入“在线”记录。需要展示完整业务数据时，使用 `tests/seed-ics-demo-data.ps1` 通过正式的“聚合存证”接口生成五个分片的可查验资料；脚本默认每个分片生成 20 条，可用 `-PerShard` 调整数量。运行时口令只通过参数传入：

```powershell
powershell -ExecutionPolicy Bypass -File tests/seed-ics-demo-data.ps1 -ApiRoot http://127.0.0.1:8098/api -Username corporate_authority -Password '<ICS权威账号密码>' -PerShard 200
```

脚本使用时间批次标识生成不重复的资产编号和索引键，可重复运行；完成后会回读首页统计和五分片在线数。百万级溯源性能数据使用 `tests/generate-million-event-index.sql`，该脚本仅扩展脱敏事件索引，不复制链下文件或伪造链上锚定。

脚本不会写入源平台数据库，也不会伪造 IPFS、Verkle 或链上字段；每条记录都会经过 ICS 正式接口，返回存证编号后即可在“数据读取”“聚合存证批量查验”和“安全事件溯源”中检索。

## 本地构建

首次克隆后启用仓库提交门禁：

```bash
bash scripts/setup-git-hooks.sh
```

提交说明首行必须包含中文。门禁拒绝 `docs`、`tmp`、缓存、依赖、构建产物、压缩包、密钥、真实 `.env` 和超过 10 MiB 的文件；提交时应按文件暂存，并在提交前执行 `git diff --cached`。

后端：

```bash
cd backend/platform-api
mvn clean test package
```

生成 `target/instrument-control-platform-api-0.1.0.jar`。

前端：

```bash
cd frontend/ics-web
npm ci
npm run build
```

生成 `frontend/ics-web/dist`，其资源基路径为 `/ics/`，接口基路径为 `/ics-api`。

## 服务器部署

服务器独立目录为 `/home/ubuntu/instrument-control-platform`。同步本目录后设置 `ICS_DB_PASSWORD`，运行：

```bash
cd /home/ubuntu/instrument-control-platform
ICS_DB_PASSWORD='<数据库密码>' bash deploy/bootstrap-server.sh
```

脚本只从当前仪控工作区构建前后端。首次执行可读取源平台的基础环境文件作为模板；生成的 `deploy/ics.env` 随后由仪控实例独立维护。

部署后执行：

```bash
bash tests/verify-server.sh
```

验收要求：`/ics/` 正常，`/ics-api/agent/*` 与 `/ics-api/federated/*` 返回 `404`，源平台 `/`、`/agent` 和 `/federated` 保持正常。