siscc/sdmxri-nsi-maapi

siscc/sdmxri-nsi-maapi 镜像文档

概述

siscc/sdmxri-nsi-maapi 是 SIS-CC .Stat Suite 的官方 NSI WS 镜像，配置用于 https://sis-cc.gitlab.io/dotstatsuite-documentation/ 安装。该镜像基于 Eurostat SDMXRI (NSI) SDMX 官方仓库构建，提供增强功能以支持 .Stat Suite 的集成需求。

该镜像在 https://gitlab.com/sis-cc/eurostat-sdmx-ri/nsiws.net.mirrored 基础上增加了以下特性：

• 配置支持 OpenId connect 认证；
• 配置使用 .Stat Suite 中定义的授权规则；
• 包含 ESTAT 的 https://gitlab.com/sis-cc/eurostat-sdmx-ri/maapi.net.mirrored/-/tree/master/src/Estat.Sri.Mapping.Tool?ref_type=heads%EF%BC%8C%E7%94%A8%E4%BA%8E%E5%88%9D%E5%A7%8B%E5%8C%96/%E6%9B%B4%E6%96%B0%E6%98%A0%E5%B0%84%E5%AD%98%E5%82%A8%E6%95%B0%E6%8D%AE%E5%BA%93%E5%AF%B9%E8%B1%A1%EF%BC%88%E9%9C%80%E7%A9%BA%E6%95%B0%E6%8D%AE%E5%BA%93%E5%8F%8A%E5%B7%B2%E5%AE%9A%E4%B9%89%E7%9A%84%E7%94%A8%E6%88%B7%E7%99%BB%E5%BD%95%EF%BC%89%E3%80%82

注意：此版本的 siscc/sdmxri-nsi-maapi 镜像仅支持 MS SQL 数据库服务器。

镜像源代码仓库：https://gitlab.com/sis-cc/.stat-suite/dotstatsuite-core-sdmxri-nsi-ws

核心功能与特性

• OpenId Connect 认证：预配置支持 OpenId connect 认证机制，增强服务安全性。
• .Stat Suite 授权规则：集成 .Stat Suite 的授权规则，实现基于数据空间的访问控制。
• MAAPI 命令行工具：内置 MAAPI 工具，用于初始化和更新映射存储数据库对象，简化数据库管理。
• MS SQL 支持：专门针对 MS SQL 数据库服务器优化，确保兼容性和稳定性。

使用场景

适用于 SIS-CC .Stat Suite 的部署与集成，特别是需要以下功能的场景：

• 管理 .Stat Suite 中的映射存储数据库结构；
• 配置基于 OpenId 的用户认证；
• 应用 .Stat Suite 定义的细粒度授权规则；
• 在容器化环境中运行 NSI WS 服务，支持 rootless 模式以增强安全性。

环境变量

以下环境变量用于配置 sdmxri-nsi-maapi 服务：

映射存储数据库配置（NSI WS）

• SQL_SERVER：托管映射存储数据库的 MS SQL 服务器实例
• SQL_DATABASE：映射存储数据库名称
• SQL_USER：应用程序用户
• SQL_PASSWORD：应用程序用户密码

MAAPI 工具变量

• MA_SQL_USER：特权用户（如 sa），需具有在 SQL_SERVER 和 SQL_DATABASE 中创建/删除/修改数据库对象的权限
• MA_SQL_PASSWORD：特权用户密码
• MA_ALWAYS_RESET：Y/N，指定容器重启时是否重置映射存储数据库（Y）或保留更改（N）
• MA_DB_VERSION（可选）：指定映射存储数据库版本（默认使用最新版本，仅在特殊需求时修改）

授权配置

• authorization__enabled（可选）：true/false，是否启用 UserAuthorizationRulesMiddlerwareBuilder 授权（默认：true，不建议修改）
• authorization__method（可选）：授权方式，固定为 "dotstat"（使用 .Stat Suite 授权规则，默认值，不建议修改）
• authorization__PrincipalFrom（可选）：授权主体来源，固定为 "context"（从上下文对象获取，默认值，不建议修改）
• mappingStore__Id__Default：NSI WS 实例的数据空间唯一标识符（用于授权规则），例如 "design"
• mappingStore__Id__FromQueryParameter（可选）：是否允许通过 GET 查询参数提供存储 ID（数据空间 ID），固定为 "Never"（默认值，不建议修改）
• DotStatSuiteCoreCommonDbConnectionString：.Stat Suite Common 数据库连接字符串（包含授权规则），例如：Server=db;Database=CommonDb;User=testLoginCommon;Password=testLogin(!)Password;

NSI Web 服务变量

• INSERT_NEW_ITEM_SCHEME_VALUES（可选）：true/false，是否允许添加新的项目方案值（如现有代码表的新代码，默认：未指定）
• SENDER_ID：数据消息头中的发送者 ID，例如 "Dissemination-DotStat"

配置相关变量

• OVERWRITE_EXISTING_CONFIG（可选）：Y/N，容器启动时是否覆盖 /app/config 目录中的现有配置文件（默认：Y，建议保持以应用环境变量配置）

其他 NSI WS 配置

更多配置选项请参考 NSI WS 文档：

• 认证：https://gitlab.com/sis-cc/eurostat-sdmx-ri/nsiws.net.mirrored/-/blob/master/doc/openid-middleware.md#configuration
• 提交的 SDMX 消息最大大小：https://gitlab.com/sis-cc/eurostat-sdmx-ri/nsiws.net.mirrored/-/blob/master/doc/CONFIGURATION.md?ref_type=heads#maximum-size-of-the-submited-sdmx-messages
• 使用 log4net 记录日志到 Google Cloud（可选）：https://gitlab.com/sis-cc/eurostat-sdmx-ri/nsiws.net.mirrored/-/blob/master/doc/CONFIGURATION.md?ref_type=heads#optional-logging-to-the-google-cloud-using-log4net
• 其他 JSON 配置元素：https://gitlab.com/sis-cc/eurostat-sdmx-ri/nsiws.net.mirrored/-/blob/master/doc/CONFIGURATION.md?ref_type=heads#other-configuration-in-json-files

使用方法

基本部署示例

启动 siscc/sdmxri-nsi-maapi（NSI WS）服务实例，监听端口 81，使用最新版本，保留结构数据库内容。

重要提示：如果在 Windows PowerShell 中运行以下命令，请将单引号替换为双引号。

示例：

sh
docker run \
-e 'auth__enabled=true' \
-e 'auth__allowAnonymous=true' \
-e 'auth__authority=http://keycloak:8080/auth/realms/${KEYCLOAK_REALM}' \
-e 'auth__clientId=stat-suite ' \
-e 'auth__requireHttps=false' \
-e 'auth__validateIssuer=false' \
-e 'auth__showPii=true' \
-e 'mappingStore__Id__Default=demo-design' \
-e 'DotStatSuiteCoreCommonDbConnectionString=Server=db;Database=CommonDb;User=testLoginCommon;Password=testLogin(!)Password;' \
-e 'SQL_SERVER=db' \
-e 'SQL_DATABASE=DesignStructDb' \
-e 'SQL_USER=testLoginDesignStruct' \
-e 'SQL_PASSWORD=testLogin(!)Password' \
-e 'MA_SQL_USER=sa' \
-e 'MA_SQL_PASSWORD=My-Mssql-Pwd-123' \
-e 'MA_ALWAYS_RESET=N' \
-e 'INSERT_NEW_ITEM_SCHEME_VALUES=true' \
-e 'SENDER_ID=.Stat-v8-demo-design' \
-e 'enableReleaseManagement=true ' \
-p 81:80 \
docker.xuanyuan.run/siscc/sdmxri-nsi-maapi:master

Rootless 模式使用

当以非 root 用户执行镜像时，需使用内置 app 用户（UID:GID=1654:1654），该用户对 /app/config 目录有写权限（由 Docker 入口脚本更新）。

示例（docker run）：

sh
docker run --rm -u app docker.xuanyuan.run/siscc/sdmxri-nsi-maapi:latest

示例（docker-compose）：

yaml
nsi-not-root:
  image: siscc/sdmxri-nsi-maapi:latest
  container_name: nsi-not-root
  user: app
  ports:
    - 80:80
  environment:
    mappingStore__Id__Default: my-dataspace
    # 其他环境变量...