API手册 - 码力引擎共享交付中心

1. 概述

码力引擎共享交付中心是整个微服务体系的统一入口和身份认证中枢。所有微服务应用都必须在此注册，并通过本中心进行路由分发和认证鉴权。

核心定位：本手册是微服务应用入驻应用导航中心的配置钥匙。任何新微服务要接入码力引擎生态，都需要按照本手册的规范完成服务注册、路由配置和认证对接。

基础信息

项目	值
服务名称	码力引擎共享交付中心 API网关
版本	v3.0.0
内网地址	http://127.0.0.1:8090
公网入口	https://share.x-aiwh.cn/gateway/
API基础路径	https://share.x-aiwh.cn/gateway/api/
认证方式	JWT Token / API Key / 设备指纹
数据库	PostgreSQL (mali_engine)
缓存	Redis

2. 系统架构

共享交付中心采用网关 + 微服务架构，网关负责统一入口、路由分发、认证鉴权，各微服务独立运行、各自管理业务逻辑。

当前已入驻服务

服务标识	服务名称	内网地址	路由前缀	状态
share_center	共享中心	http://127.0.0.1:8266	/share	离线
office_assistant	X-AI办公助手	http://127.0.0.1:8081	/office	运行中
maintain	服务器管理	http://127.0.0.1:8091	/maintain	运行中

请求流转

# 用户请求流程
用户浏览器 → nginx(443) → 网关(8090) → 微服务(8081/8091/8266)
                 ↓
           认证鉴权(JWT/API Key)
                 ↓
           路由分发(/{service_key}/{path})

3. 认证体系

共享交付中心支持三种认证方式，所有需认证的API接口可任选其一：

方式一：API Key（推荐用于脚本/桌面端）

X-API-Key: xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key在用户登录后通过/api/auth/api-key接口生成，长期有效，可随时重新生成（旧Key自动失效）。

方式二：JWT Token（用于Web前端）

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT Token通过登录接口获取，有效期7天。过期后需重新登录。

方式三：设备指纹（用于浏览器免密）

Cookie: device_token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

登录成功后自动设置，有效期30天。同一设备再次访问时自动续期，无需重新登录。

注意：三种方式可组合使用。优先级：API Key > JWT Token > 设备指纹。

4. 用户注册

POST/api/auth/register

注册新用户，系统自动生成16位随机密码并发送到邮箱

参数	类型	必填	说明
username	string	是	用户名（3-20位字母数字）
email	string	是	邮箱地址（需可接收邮件）
user_type	string	否	用户类型：free/pro/enterprise，默认free

# 请求示例
curl -X POST https://share.x-aiwh.cn/gateway/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"newuser","email":"user@example.com"}'

# 响应示例
{
  "code": 0,
  "msg": "注册成功，密码已发送至邮箱",
  "data": {"username": "newuser", "user_type": "free"}
}

说明：注册成功后，系统会自动生成16位随机密码并发送到用户邮箱。用户需用该密码登录后可修改密码。

5. 用户登录

POST/api/auth/login

用户登录，返回JWT Token并设置设备指纹Cookie

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码
remember_device	boolean	否	是否记住设备（30天免密），默认true

# 请求示例
curl -X POST https://share.x-aiwh.cn/gateway/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

# 响应示例
{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 5,
      "username": "admin",
      "email": "xiongchunguan@qq.com",
      "user_type": "enterprise",
      "is_admin": true
    }
  }
}
# 同时设置Cookie: device_token=xxx（30天有效）

6. 密码管理

6.1 发送重置验证码

POST/api/auth/reset-code

向用户邮箱发送6位验证码（10分钟有效）

参数	类型	必填	说明
email	string	是	注册邮箱

6.2 重置密码

POST/api/auth/reset-password

使用验证码重置密码

参数	类型	必填	说明
email	string	是	注册邮箱
code	string	是	6位验证码
new_password	string	否	新密码（不填则系统生成随机密码）

6.3 修改密码

POST/api/auth/change-password

修改当前用户密码（需登录认证）

参数	类型	必填	说明
old_password	string	是	当前密码
new_password	string	是	新密码（至少8位）

7. API Key管理

7.1 生成API Key

POST/api/auth/api-key

生成或重新生成API Key（需登录认证，旧Key自动失效）

# 请求示例
curl -X POST https://share.x-aiwh.cn/gateway/api/auth/api-key \
  -H "X-API-Key: xai-当前key"

# 响应示例
{
  "code": 0,
  "msg": "API Key生成成功",
  "data": {"api_key": "xai-96197ac8df7bab51551e559fe48f4ba6b96d65bc59f1801d"}
}

7.2 获取当前用户信息

GET/api/auth/me

获取当前登录用户信息（需认证）

# 响应示例
{
  "code": 0,
  "data": {
    "id": 5,
    "username": "admin",
    "email": "xiongchunguan@qq.com",
    "user_type": "enterprise",
    "is_admin": true,
    "api_key": "xai-96197ac8..."
  }
}

8. 设备管理

8.1 获取已登录设备列表

GET/api/auth/devices

获取当前用户所有已登录设备（需认证）

8.2 撤销设备

DELETE/api/auth/devices/{device_id}

撤销指定设备的登录状态（需认证）

8.3 退出登录

POST/api/auth/logout

退出当前设备登录（需认证）

8.4 退出所有设备

POST/api/auth/logout-all

退出所有设备登录（需认证）

9. 服务列表

GET/api/services

获取所有已注册的微服务列表（含健康状态）

# 请求示例
curl https://share.x-aiwh.cn/gateway/api/services

# 响应示例
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "service_key": "share_center",
      "service_name": "共享中心",
      "service_url": "http://127.0.0.1:8266",
      "route_prefix": "/share",
      "icon": "📁",
      "description": "文件共享、在线预览、客户码管理",
      "health_status": "offline",
      "last_health_check": "2026-07-02T08:00:00"
    }
  ]
}

10. 路由代理

GET/POST/PUT/DELETE/{service_key}/{path}

动态路由代理：将请求转发到对应微服务

路由规则

# 路由格式
/gateway/{service_key}/{path} → http://{service_url}/{path}

# 示例
/gateway/office/api/chat     → http://127.0.0.1:8081/api/chat
/gateway/maintain/api/v1/system/info → http://127.0.0.1:8091/api/v1/system/info
/gateway/share/api/v1/files  → http://127.0.0.1:8266/api/v1/files

说明：网关会自动转发请求头（含认证头）、请求体、查询参数。响应原样返回，支持流式响应。

支持的HTTP方法

GET - 查询请求
POST - 创建/提交
PUT - 更新
DELETE - 删除
PATCH - 部分更新
OPTIONS - CORS预检

11. 健康检查

GET/api/health

网关自身健康检查

# 响应示例
{
  "status": "ok",
  "service": "mali-engine-gateway",
  "version": "3.0.0",
  "timestamp": "2026-07-02T08:00:00"
}

后台任务：网关每60秒自动检查所有注册服务的健康状态，更新health_status字段（healthy/unhealthy/offline）。

12. 微服务入驻指南

核心流程：新微服务要入驻应用导航中心，需完成以下4步。

步骤一：开发微服务

使用FastAPI/Flask等框架开发微服务，监听内网端口（如8092、8093等）
实现/api/health健康检查接口，返回{"status":"ok"}
接入共享认证模块（mali_auth.py），使用verify_auth依赖进行鉴权
创建systemd服务文件，设置开机自启

步骤二：注册服务

在/data/mali_engine/shared/python/mali_config.py的SERVICES字典中添加服务配置：

SERVICES = {
    # ... 已有服务 ...
    "your_service": {
        "name": "你的服务",           # 显示名称
        "url": "http://127.0.0.1:8092", # 内网地址
        "prefix": "/your-service",      # 路由前缀（用于前端跳转）
        "icon": "🎯",                 # 图标（emoji）
        "desc": "服务描述文字",         # 描述
    },
}

步骤三：重启网关

# 重启网关使配置生效
sudo systemctl restart mali-gateway.service

# 验证服务已注册
curl http://127.0.0.1:8090/api/services | python3 -m json.tool

步骤四：验证入驻

访问 https://share.x-aiwh.cn/gateway/ 查看应用导航中心，新服务卡片应出现
点击卡片进入服务，验证功能正常
检查健康状态显示为"运行中"（绿色）

入驻规范要求

要求项	规范
健康检查	必须实现 `GET /api/health` 返回200
认证对接	必须接入 `mali_auth.verify_auth` 进行鉴权
端口分配	使用8090-8999区间端口，避免冲突
日志输出	输出到 `/data/mali_engine/logs/{service_name}.log`
systemd服务	命名 `mali-{service}.service`，设置开机自启
首页路由	提供 `GET /` 返回HTML管理界面
API路径	统一使用 `/api/v1/` 前缀

13. 完整调用示例

13.1 Python调用示例

import requests

BASE = "https://share.x-aiwh.cn/gateway"
API_KEY = "xai-96197ac8df7bab51551e559fe48f4ba6b96d65bc59f1801d"

# 1. 获取服务列表
resp = requests.get(f"{BASE}/api/services")
print(resp.json())

# 2. 调用办公助手API（带认证）
resp = requests.post(
    f"{BASE}/office/api/chat",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json={"message": "你好"}
)
print(resp.json())

# 3. 调用服务器管理API
resp = requests.get(
    f"{BASE}/maintain/api/v1/nodes",
    headers={"X-API-Key": API_KEY}
)
print(resp.json())

13.2 JavaScript调用示例

const BASE = 'https://share.x-aiwh.cn/gateway';
const API_KEY = 'xai-96197ac8df7bab51551e559fe48f4ba6b96d65bc59f1801d';

// 获取服务列表
const resp = await fetch(`${BASE}/api/services`);
const data = await resp.json();
console.log(data);

// 调用带认证的API
const resp2 = await fetch(`${BASE}/maintain/api/v1/nodes`, {
  headers: { 'X-API-Key': API_KEY }
});
const data2 = await resp2.json();
console.log(data2);

13.3 curl调用示例

# 获取服务列表
curl https://share.x-aiwh.cn/gateway/api/services

# 用户登录
curl -X POST https://share.x-aiwh.cn/gateway/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

# 调用服务器管理（多节点）
curl https://share.x-aiwh.cn/gateway/maintain/api/v1/nodes \
  -H "X-API-Key: xai-96197ac8df7bab51551e559fe48f4ba6b96d65bc59f1801d"

# 获取渲染节点系统信息
curl https://share.x-aiwh.cn/gateway/maintain/api/v1/nodes/render/system/info \
  -H "X-API-Key: xai-96197ac8df7bab51551e559fe48f4ba6b96d65bc59f1801d"

14. 错误码说明

HTTP状态码	含义	处理建议
200	成功	-
400	请求参数错误	检查请求体格式和必填参数
401	未认证/认证失败	检查API Key/Token是否有效
403	无权限	确认账户是否有管理员权限
404	服务/资源不存在	检查service_key和路径是否正确
429	请求频率超限	降低调用频率，检查用户类型配额
500	服务器内部错误	查看服务日志排查
503	服务不可用	微服务未运行，检查systemd状态

用户类型配额

用户类型	API/小时	AI调用/天	上传/小时
free	50	5	10
pro	500	500	100
enterprise	5000	5000	1000

技术支持：如有问题，请联系邮箱 xiongchunguan@qq.com，或通过服务器管理界面查看服务日志。

📖 API手册 - 码力引擎共享交付中心

导航目录