shermanloan/sce-api-server

SCE API Server Docker镜像文档

镜像概述和主要用途

SCE API Server为Sherman计算引擎(SCE)提供HTTP REST接口，通过Docker打包，支持在Linux/amd64和Linux/arm64平台运行。该镜像便于合作伙伴在本地或云环境中快速部署一个或多个SCE实例，实现对SCE的远程访问和计算请求处理。

核心功能和特性

• 跨平台支持：兼容Linux/amd64和Linux/arm64架构
• API接口：提供RESTful接口，支持版本查询、单XML请求、批量请求及JSON请求
• 安全认证：通过API密钥（ApiKey）验证请求合法性
• 日志管理：支持日志级别配置，Docker环境下日志重定向至标准输出，可通过docker logs查看
• 数据路径限制：支持RootPath配置，限制数据目录访问范围，增强安全性
• 批量处理：提供批量请求接口，支持JSON数组或对象形式的多请求并发处理

使用场景和适用范围

适用于需要通过网络接口访问Sherman计算引擎的合作伙伴，可部署在：

• 本地服务器环境
• 私有云或公有云平台（如AWS、Azure、阿里云等）
• 需批量处理计算请求的业务场景
• 对API访问进行权限控制和日志审计的企业环境

快速启动

步骤1：运行SCE API Server Docker容器

bash
$ docker run -d -p8080:8080 --name sce-api shermanloan/sce-api-server

上述命令将以默认配置启动最新版本的SCE API Server容器。默认配置下，容器监听8080端口。如需自定义配置或调用API，需参考下文详细说明。注意：使用SCE API Server需提供有效的API密钥。

镜像内容说明

• data/：包含示例配置文件目录，用于配置特定账户的计算和保险设置
• samples/：包含支持的各类SCEX XML请求示例
• xml/：包含所有SCEX请求（输入）的DTD文件；其子目录Output/包含所有SCEX响应（输出）的DTD文件
• Dockerfile：Docker镜像构建文件
• README.md：镜像说明文档
• sce-api-server：SCE API Server主程序
• sce-api-server.cfg：SCE API Server配置文件
• sce-api-server-health-check：用于验证sce-api-server运行状态的健康检查程序

配置说明

SCE API Server的核心配置通过sce-api-server.cfg文件实现，默认内容如下：

ini
[Settings]
Port=8080
LogLevel=0
LogFile=/var/log/sce-api-server.log
RootPath=
ApiKey=

配置参数详解

Port

• 描述：服务器监听HTTP客户端连接的端口号
• 默认值：8080
• 取值范围：1-65535

LogLevel

• 描述：控制日志输出详细程度
  • 0：仅记录错误、服务启停/暂停/恢复等关键信息（默认）
  • 1：增加连接信息（远程地址、URL、使用的API密钥）
  • 2：增加客户端请求内容
  • 3：增加服务器响应内容
• 注意：LogLevel≥1时可能生成大量日志，需监控日志文件所在文件系统的可用空间

LogFile

• 描述：日志文件路径配置
  • 若值为system，使用系统日志文件
  • 否则，指定日志文件的绝对路径
• Docker环境特殊处理：Dockerfile中已将默认日志文件/var/log/sce-api-server.log重定向至/dev/stdout，因此可通过docker logs命令查看日志

RootPath

• 描述：设置数据目录路径前缀，限制API调用的数据目录访问范围
  • 示例：若设为/etc/sce/，则API调用仅允许访问/etc/sce/的子目录
  • 若留空，API调用可指定任意目录路径
• 关联：与API请求头中的x-sce-datapath字段配合使用，仅在需要使用setup文件（见data/目录说明）时生效

ApiKey

• 描述：配置默认API密钥，用于请求验证
  • 若未设置，所有请求需在头信息中包含x-sce-apikey字段
  • 若设置，请求中包含的x-sce-apikey字段将覆盖默认值

API接口说明

所有接口共享请求头、响应码和响应头字段规范，具体端点如下：

请求头字段

• x-sce-datapath：指定默认数据目录路径。若RootPath已配置，该值将附加到RootPath后形成完整路径
• x-sce-apikey：请求的API密钥。若配置文件中已设置ApiKey，该字段可选；否则为必填

响应码

• 200：API密钥有效，请求已提交至SCE且处理成功
• 401：未授权访问，API密钥无效
• 500：服务器错误，SCEX或SCE API Server处理请求时出错

响应头字段

成功响应包含：

• Content-Type：根据响应类型设为application/xml或application/json
• x-sce-apikey-expires：API密钥的过期日期
• 响应体：SCE API Server返回的计算结果

端点文档

版本查询

• 请求方法：GET
• URL：http://server:port/scex/api/v1/version
• 描述：查询SCEX的版本信息

SCEX XML请求

• 请求方法：POST
• URL：http://server:port/scex/api/v1/request
• 请求体：SCEX XML请求内容
• 说明：支持的XML请求格式详见SCEX参考手册

SCEX批量请求

• 请求方法：POST
• URL：http://server:port/scex/api/v1/batch
• 请求体：JSON对象或数组，包含多个XML请求
• 处理规则：
  • JSON对象：字段名为字符串且以"SCEX"结尾的字段值将作为XML请求处理，响应中保留原字段名，值为SCEX响应XML；其他字段原样返回
  • JSON数组：数组中的字符串元素作为XML请求处理，非字符串元素忽略，响应为包含处理结果的数组

JSON对象请求示例：

json
{
    "Version_SCEX": "<inVERSION/>",
    "Accounts_SCEX": "<inACCOUNT/>",
    "DoNotParse": "因字段名不以SCEX结尾，不会被SCEX解析"
}

JSON数组请求示例：

json
["<inVERSION/>", "<inACCOUNT/>"]

SCEJSON请求

• 请求方法：POST
• URL：http://server:port/scejson/api/v1/request
• 请求体：SCE JSON请求内容
• 说明：支持的JSON请求格式详见https://github.com/shermanloan/scejson-doc

版本历史

Release 2025-10

• 新增：SCE API Server支持根路径强制限制。配置RootPath后，所有数据路径（通过x-sce-datapath头或字段/属性指定）将附加到RootPath，形成"监狱"机制，防止路径越权；请求路径会被清理以确保无法逃离限制
• 新增：API密钥日志记录优化。当LogLevel≥1（默认0）时，请求日志中仅记录API密钥的前4个字符，后跟"+..."；无效API密钥仍完整记录

Release 2025-07

• 新增：所有JSON响应的Content-Type从application/xml改为application/json
• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2025-04

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2025-01

• 新增：基础Linux镜像从Alpine 3.18更新至3.20
• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2024-10

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2024-07

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2024-04

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2024-01

• 新增：基础Linux镜像从Alpine 3.16更新至3.18
• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2023-10

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2023-07-1

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2023-07

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2023-04

• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2023-01

• 基础Linux镜像从Ubuntu 22.04改为Alpine 3.16，以减小镜像体积
• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2022-10

• 此前版本中，调用SceX和SceJson端点需两个独立API密钥，本版本支持单API密钥访问两者
• 基础Linux镜像从Alpine 3.14改为Ubuntu 22.04，以提供glibc兼容性
• 接口变更详情见发送给合作伙伴的SCE更新公告

Release 2022-07

• SCE API Server无变更，接口变更详情见发送给合作伙伴的SCE更新公告

Release 2022-04

• 新增：首个多架构构建版本，支持Linux/amd64和Linux/arm64平台
• 新增：添加/scejson/api/v1/request API资源，JSON接口支持的SCE模块详见上文SCEJSON文档
• 修复：解决/scex/api/v1/batch资源中的内存分配错误

Release 2022-01

• 新增：基础Linux镜像从Alpine 3.11更新至3.14
• 新增：SCEX Http API Server重命名为SCE API Server，镜像中部分文件名变更，但功能与旧版本一致（含新增功能）
• 新增：SCEX API Server新增批量请求URL /scex/api/v1/batch，支持通过POST请求体发送多个XML请求：
  • JSON数组：数组中的字符串元素作为独立XML请求发送至SCEX，非字符串元素忽略并原样返回
  • JSON对象：字段为字符串且名称以"SCEX"结尾的字段值作为XML请求处理，响应中对应字段值为SCEX返回的XML；其他字段原样返回

联系我们

• J. L. Sherman and Associates官网