# x-platform

**Repository Path**: code-me/x-platform

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# x-platform 数据安全分析平台

企业级数据安全分析平台：React 19 + TypeScript + Vite + Ant Design 控制台前端（安全与合规工作台、威胁运营、专项监测、调查响应、算力与智能体运行等），配套 FastAPI 后端——多数据库 SPL 查询服务（PostgreSQL / ClickHouse / Elasticsearch / Redis / Neo4j）+ 插件化 AI 智能体内核。

## 仓库结构

```text
.
├── frontend/   React + TS + Vite + Ant Design 控制台前端（FSD 分层）
├── server/     FastAPI 多数据库 SPL 查询服务（PostgreSQL / ClickHouse / Elasticsearch / Redis）
├── scripts/    安装部署、前后端服务启停和网关辅助脚本
├── tools/      数据库结构提取脚本
└── docs/       架构、功能地图、开发规范与运行手册
```

前端是仓库的主体，`server/` 为可选的后端查询服务，二者可独立运行。

## 快速开始（前端）

```bash
cd frontend
npm install
npm run dev
```

默认访问 `http://localhost:5173/`。

| 命令 | 用途 |
| --- | --- |
| `npm run dev` | 启动开发服务器 |
| `npm run lint:fsd` | 检查 FSD 层级、依赖方向和公共 API |
| `npm run typecheck` | 执行 TypeScript 检查 |
| `npm run test` | 运行 vitest 单元测试 |
| `npm run build` | 类型检查并生成生产构建 |
| `npm run check` | 执行 FSD 检查和生产构建 |
| `npm run preview` | 预览最近一次构建产物 |

后端服务见 [`server/README.md`](server/README.md)。

## 一键安装部署

首次部署可直接执行：

```bash
./scripts/install.sh
```

脚本默认按 `production` 档位安装后端依赖、前端依赖并生成前端生产产物，然后启动前后端进程。首次运行会创建 `server/.env`、`frontend/.env` 和 `var/` 运行目录；preview 或显式 `--api-base` 时还会创建/更新不入库的 `frontend/.env.production.local`，确保生产构建读取部署覆盖；不会覆盖已有配置文件，只会补充部署所需的 profile、生产安全默认值和缺失密钥。生产档位缺少 `AUTH_JWT_SECRET` 或管理员初始口令时自动生成，凭据保存于 `var/credentials.txt`（权限 600）。数据库、Redis、LLM 等外部依赖仍需按环境填写 `server/.env`。

常用选项：

```bash
./scripts/install.sh --profile dev --no-start
./scripts/install.sh --skip-build
./scripts/install.sh --systemd --systemd-scope system
```

Linux 上使用 `--systemd` 会安装并启用 `x-platform-backend.service` 与 `x-platform-frontend.service`；没有 systemd 的 macOS、Linux 或 Git Bash 环境使用进程模式。

## 服务启动管理

`scripts/service.sh` 是统一服务管理入口：按端口清理旧进程、用正确的 Node/uv 环境拉起、轮询 liveness 健康检查后再返回。后端固定**不带** `--reload`（前端外壳的 SSE 长连接会导致 WatchFiles 重载卡死），所以改完后端代码或 `.env` 后需要重启后端。旧入口 `scripts/restart-services.sh` 仍可使用。

```bash
./scripts/service.sh start               # 启动前后端
./scripts/service.sh stop                # 停止前后端
./scripts/service.sh restart             # 重启前后端
./scripts/service.sh status              # 查看端口与健康状态
./scripts/service.sh logs                # 跟踪日志
./scripts/service.sh supervise            # 进程模式看门狗
./scripts/service.sh install-systemd      # Linux 安装 systemd 单元
```

安装脚本生成的部署参数保存在 `var/x-platform.env`，可用 `SERVICE_ENV_FILE` 指向其他文件。可用 `BACKEND_PORT`、`FRONTEND_PORT`、`HEALTH_TIMEOUT`、`LOG_DIR`、`PID_DIR` 覆盖默认值；安装部署后的日志默认写入 `var/log/`，手动运行服务脚本时仍默认写入 `/tmp/`。

## 当前页面

| 页面 | 地址 | 外壳 | 状态 |
| --- | --- | --- | --- |
| 原安全与合规工作台 | `/security` | 顶栏 + 右侧工具栏 | 静态工作台 |
| 网络威胁检测控制台 | `/threat-dashboard` | 独立控制台顶栏 + 左侧导航 | 静态工作台 |
| 卡券 | `/coupons` | 顶栏 + 左侧导航 + 右侧工具栏 | Mock 数据工作台 |
| 数据库结构查询 | `/db-schema` | 顶栏 + 左侧导航 + 右侧工具栏 | 结构快照查询 |
| 图数据库查询 | `/graph-query` | 顶栏 + 左侧导航 + 右侧工具栏 | Neo4j Cypher / SPL 查询 |
| PoC 验证台 | `/poc-verify` | 顶栏 + 左侧导航 + 右侧工具栏 | 白名单 + 沙箱验证（需登录） |
| qiankun 子应用 | `/apps/*` | 主应用外壳 + 共享访问上下文 + 子应用容器 | 已接入运营大屏（`/apps/operations-screen`，入口 `localhost:35080`） |
| 组织管理 | `/access-control` | 主应用管理页，可拆为 qiankun 子应用 | 组织、成员、角色和权限集合 |

页面路由注册、地址解析和懒加载统一维护在 [`frontend/src/app/router/routes.ts`](frontend/src/app/router/routes.ts)。旧版 `#/...` 和 `?page=...` 地址会自动迁移到 history 地址。

数据库结构查询页的数据由 [`tools/db-schema/extract_schema.py`](tools/db-schema/README.md) 从内网数据库只读提取（凭据走环境变量，含可选的 Neo4j 图源），结构变化后重新运行即可同步页面数据与文档。

## 文档

从 [`docs/README.md`](docs/README.md) 进入文档中心：

- [项目知识地图](docs/knowledge-map.md)：一张结构图看懂全貌，并导航到各专项文档
- [L01–L07 能力分层设计](docs/layers-design.md)：AI 能力（能力在上）与信任体系（信任在下）的七层模型
- [架构说明](docs/architecture.md)：FSD 层级、依赖方向、公共 API 和扩展方式
- [功能地图](docs/feature-map.md)：页面、外壳、共享能力和配置入口
- [数据库表结构](docs/database-schema.md)：各数据源的表、字段、索引和约束结构
- [SPL 查询引擎](docs/spl-query.md)：SPL 语法、支持的命令与执行语义
- [GraphQL 多库多表查询](docs/graphql-query.md)：按库表动态 schema 与 Hasura 风格 where
- [后端架构](docs/backend-architecture.md)：FastAPI 查询服务分层、下推与 GraphQL 入口
- [开发规范](docs/开发规范.md)：命名、类型、React、样式和数据约定
- [运行与验证](docs/runbook.md)：安装、命令、环境变量、冒烟检查和故障排查

## 技术栈

- 前端：React 19、TypeScript 5、Vite 7、Ant Design 6、qiankun 2、CSS Modules、i18next
- 后端：FastAPI、asyncpg、clickhouse-driver、redis.asyncio、elasticsearch、strawberry-graphql

## 当前边界

- 多数业务页仍以页面切片内的 Mock/静态数据为主；威胁看板已接告警/聚合 REST。通用多库查询服务见 [`server/README.md`](server/README.md) 与 [`docs/graphql-query.md`](docs/graphql-query.md)。
- CI 已接入 GitHub Actions（前端 typecheck/build/vitest + 后端 pytest）；前端 FSD lint 存量债务暂以非阻塞方式暴露。提交前本地执行 `npm run check` 并完成浏览器冒烟验证。
- 路由使用轻量 history 实现，页面数量明显增长后再评估完整路由库。
- qiankun 主应用已提供 `initGlobalState` 访问上下文广播；运营大屏子应用经 `VITE_QIANKUN_APPS_JSON` 配置入口，其余子应用按同样方式接入并订阅 `globalState`。
- 后端鉴权按三档分级（读/写/管理），运行档位与生产部署检查清单见 [`docs/runbook.md`](docs/runbook.md)