面向多源异构国产算力的开源 AI 开发运维一体化平台

作者：冀荣丽、李锦冬、刘子康、单逸飞、李爽、周伟、周锐、周洋

本文档面向参与平台优化的同学，帮助快速了解平台架构、本地开发部署方式，以及新增功能板块的标准流程。

一、平台总体架构

平台采用 「控制平面 + 可插拔算力节点」 架构：

                        用户浏览器
                            │  HTTPS
                            ▼
              ┌─────────────────────────┐
              │  控制平面 ECS（永远在线）  │  114.116.226.154  lanjiangzhiyan.com
              │  ├── nginx (80/443)      │  静态托管前端 dist + 反代 /api
              │  ├── FastAPI 后端 :8001  │  systemd 托管（jrl-backend）
              │  ├── SQLite/PG 数据库     │  用户/订单/账单/作业元数据
              │  └── OBS 对象存储         │  数据集/模型中央仓库（cangku-pt 桶）
              └────────────┬────────────┘
                           │ SSH 纳管 / 反向隧道(chisel)
          ┌────────────────┼────────────────┬──────────────┐
          ▼                ▼                ▼              ▼
      昇腾910B4节点     天数智芯节点      沐曦MetaX节点    燧原S60节点
      (NPU, CANN)      (GPU, CoreX)     (GPU, MACA)     (GPU, TopsRider)
      各节点运行 runner / 常驻推理 daemon，由控制面统一下发训练/推理任务

控制平面（本仓库代码）：用户系统、算力市场、计费、训练作业调度、数据标注、模型库等全部业务逻辑，部署在华为云 ECS 上。
算力节点：各厂商 GPU/NPU 服务器，通过 SSH 被控制面纳管，接收训练/推理下发任务，本地执行后回传结果。
对象存储 OBS：数据集、模型权重的中央仓库，节点需要时从 OBS 拉取，产物回传 OBS 归档。

二、线上环境

项目	值
平台网址	https://lanjiangzhiyan.com
管理员账号	admin（密码见《平台密钥.docx》，找组长索取）
ECS 服务器	114.116.226.154（Ubuntu 24.04，SSH 凭据见密钥文档）
ECS 代码路径	`/opt/jrl`（git 仓库）
后端服务	`systemctl status jrl-backend`（uvicorn :8001）
前端	本地构建后 dist 上传，nginx 静态直供
OBS 桶	cangku-pt（cn-north-4），数据集/模型前缀 `平台数据集模型/`
代码仓库	gitlink.org.cn/RongliJi/jrl-platform（邀请链接见密钥文档）

⚠️ 密钥、密码等敏感信息不要提交到 git 仓库，统一从《平台密钥.docx》获取。

三、本地开发环境搭建

1. 拉取代码

git clone https://www.gitlink.org.cn/RongliJi/jrl-platform.git
cd jrl-platform

2. 后端（Python 3.12+）

cd backend
pip install -r requirements-windows.txt   # 通用环境（无 NPU）
# requirements.txt 含昇腾镜像内本地 wheel 路径，仅 ModelArts 昇腾环境可用

python -m uvicorn api:app --host 0.0.0.0 --port 8001 --reload

3. 前端（Node 20+ / npm 10+）

cd frontend
npm install
npm run dev      # 开发模式 :5173，自动代理 /api → localhost:8001
npm run build    # 生产构建，产物在 frontend/dist/

4. 验证

浏览器打开 http://localhost:5173，用 admin 登录（本地库首次启动自动初始化默认账号）。

四、目录结构速览

jrl-platform/
├── backend/                      # 后端（FastAPI，端口 8001）
│   ├── api.py                    # API 主入口（路由总注册、全局中间件）
│   ├── auth.py                   # 认证与用户分级（admin/普通用户 × L1/L2/L3）
│   ├── billing/                  # 算力市场/计费（独立子模块，router.py 出口）
│   ├── data_annotate.py          # 数据标注（含 AI 自动标注）
│   ├── annotate_pk.py            # 标注PK台（人机对比）
│   ├── jobs.py                   # 训练作业调度
│   ├── server_manager.py         # 算力节点 SSH 纳管（含连接池 _acquire_ssh）
│   ├── obs_storage.py            # OBS 对象存储读写
│   ├── science_discovery/        # 科学发现板块（独立包，router 出口）
│   ├── embodied_convert/         # 具身数据转换（独立包，api_routes 出口）
│   └── ...
├── frontend/                     # 前端（React 18 + TypeScript + Vite 6 + antd 5）
│   └── src/
│       ├── App.tsx               # 路由注册 + 板块菜单（sections 配置）
│       ├── pages/                # 页面组件（每板块一个 .tsx，billing/ 为子目录）
│       ├── api/                  # API 客户端封装（client.ts 统一 fetch）
│       └── components/           # 公共组件
├── workspace/                    # 运行时数据（数据集/模型权重/DB，不入库）
└── README.md

模块划分惯例：后端一个业务板块 = 一个 .py 模块或一个子包；前端一个页面 = pages/ 下一个 .tsx（大板块可用子目录，如 pages/billing/）。

五、如何加入一个新板块（标准流程）

以新增「我的板块」为例，完整走一遍：

后端：3 步

① 新建路由模块 backend/my_feature.py：

from fastapi import APIRouter

router = APIRouter(prefix="/api/my-feature", tags=["my-feature"])

@router.get("/list")
async def list_items():
    return {"records": []}

API 路径命名对齐现有风格：/api/<模块>/<资源>/<动作>（参考 /api/annotate/{project_id}/suggest-classes）。
字段匹配用精确匹配，不用子串模糊匹配。

② 在 backend/api.py 注册（约 558 行起的路由注册区，仿照 science_discovery 的写法）：

try:
    from my_feature import router as my_feature_router
    app.include_router(my_feature_router)
except Exception as _e:
    print(f"[my_feature] 路由加载失败: {_e}")

用 try/except 包裹是本项目惯例：单个板块出错不拖垮整个后端。

③ 如需登录态/权限：依赖注入 auth 模块的 require_perm("xxx:yyy")，并在权限矩阵中登记新权限点（参考 auth.py 现有 perm 定义）。

前端：4 步

① 新建页面 frontend/src/pages/MyFeature.tsx（React + TSX，用 antd 组件，参考现有页面如 Compat.tsx）。

② 在 frontend/src/App.tsx 注册懒加载（约 51 行起的 lazy 区）：

const MyFeature = React.lazy(() => import('./pages/MyFeature'));

③ 在 App.tsx 加路由（约 440 行起的 Route 区）：

<Route path="/my-feature" element={<PageWrapper><MyFeature /></PageWrapper>} />

④ 在 App.tsx 的 sections 配置中挂入菜单（约 108 行起）：选择要归属的大板块（任务大厅/数据/模型/算力市场/功能/系统/个人），在其 options 数组里加一项：

{ key: 'my-feature', title: '我的板块', description: '功能简介',
  icon: <ToolOutlined />, path: '/my-feature', perm: 'myfeature:view' },

perm 可选：配置后按用户等级权限控制可见性；不写则默认可见。
adminOnly: true 的大板块（如「系统」）仅管理员可见。

API 调用封装

前端请求统一走 frontend/src/api/client.ts 的封装（带 token、错误处理），不要裸写 fetch（裸 fetch 静默失败曾导致 PK 台”功能丢失”事故）。涉及创建/支付/状态变更的 POST 必须带幂等键（参考 withIdempotency 用法）。

自测清单

cd backend && python -m py_compile my_feature.py 通过
cd frontend && npm run build 通过
本地起前后端，页面能进、接口 200、无控制台报错

六、部署到线上 ECS

ECS 上没有 node/npm，前端必须本地构建后上传产物；后端直接同步代码重启。

本地提交并推送到 gitlink 仓库对应分支。
后端：代码同步到 ECS /opt/jrl 后 systemctl restart jrl-backend，然后 curl 验证接口。
前端：本地 npm run build → 打包 dist/ 上传 → 覆盖 ECS 上 nginx 静态目录 → 强刷浏览器验证。
部署后必须验证：页面能打开、接口不 502、改动功能真实可用。

七、协作与编码规范

分支：每人从主分支拉自己的功能分支（如 feature/xxx），完成自测后提合并，不要直接推主分支。
Python：文件名用 snake_case（如 obs_storage.py），代码标识符用英文。
前端：React + TypeScript（TSX），UI 用 Ant Design 5，新增依赖先告知组长。
术语：界面文案用「视觉任务」而非「检测任务」；是 CUDA 不是 coda——注意拼写。
视觉风格：全站蓝绿科技风，动画要淡雅，不做花哨/闪光类循环动效。
密钥纪律：AK/SK、密码、JWT 密钥只放 .env 或密钥文档，严禁写进代码或 README 提交。

八、常见问题

Q: requirements.txt 安装报错找不到 whl？ A: 该文件含昇腾镜像内本地 wheel 路径，本地开发请用 requirements-windows.txt。

Q: 前端页面能开但接口 401？ A: 后端重启后旧 token 失效，重新登录即可。

Q: 刷新子页面白屏？ A: 确认 vite.config.ts 的 base 为 '/'（相对路径 ./ 会导致深层路由资源 404）。

Q: 数据集广场/模型库列表为空？ A: 平台按目录扫描：数据集须在 workspace/datasets/<id>/（含 images/train、data.yaml），模型须在 workspace/*.pt。

Q: 跨节点调用的接口很慢（2~4s）？ A: 正常现象是走 SSH 连接池；新写远端命令必须用 server_manager._acquire_ssh/exec_command，不要裸建新连接，高频轮询接口加 TTL 缓存。

九、技术栈与版本

层	技术	版本
后端	Python + FastAPI + Uvicorn	Python 3.12+ / FastAPI 0.141
前端	React + TypeScript + Vite	React 18 / Vite 6 / TS 5.6
UI 库	Ant Design 5 + Monaco Editor + Recharts + three.js	—
数据库	SQLite（aiosqlite）+ PostgreSQL（计费）	—
认证	JWT（PyJWT + bcrypt）	—
算力	昇腾 910B4 / 天数智芯 / 沐曦 / 燧原 / 摩尔线程	CANN 8.5.2
检测	Ultralytics YOLO（含 OBB 旋转框）	8.4+
存储	华为云 OBS（cangku-pt）	—