快速上手

安装 Pain001:pip、Docker 与首个验证文件

Python 3.11+、pip 或 Docker,三条命令生成一个通过校验的支付文件。

Pain001 可在 macOS、Linux 与 Windows 上运行于 Python 3.11+(每个版本均在 CI 中测试)。按需安装即可;所有可选能力均为附加依赖(extra),基础安装保持精简。


01. PyPI#

所需能力 命令
核心 CLI 与 Python 库 pip install pain001
REST API 微服务(FastAPI + Uvicorn) pip install "pain001[api]"
Parquet 数据摄取(PyArrow) pip install "pain001[parquet]"
PGP 加密输入文件(.gpg / .asc) pip install "pain001[gpg]"
为 API 提供的 Redis 异步任务队列 pip install "pain001[redis]"
OpenTelemetry 链路追踪 pip install "pain001[otel]"
内置的精简 MCP / LSP 服务器 pip install "pain001[mcp]" / "pain001[lsp]"
SFTP delivery (pain001 upload) pip install "pain001[upload]"
Private CEL policy rules (--rules) pip install "pain001[rules]"
Faster XSD validation (lxml) pip install "pain001[fast]"
XML signing and verification (--xml-sign-key, verify-signature) pip install "pain001[sign]"

配套包需单独安装,并与核心同步发布:每个配套包版本的版本号都与其所需的核心版本相同。

pip install pain001-loader-xlsx    # Excel ingestion (auto-discovered plugin)
pip install pain001-loader-mt101   # SWIFT MT101 parsing library
pip install pain001-mcp            # Full MCP server for AI agents
pip install pain001-lsp            # Editor language server

验证安装并浏览报文目录:

pain001 --version
pain001 versions          # list every supported message definition
pain001 init pain.001.001.09   # write a starter CSV, ./pain.001.001.09.csv

02. Docker#

多架构镜像(linux/amd64、linux/arm64)发布至 GitHub Container Registry。容器以专用非 root 用户运行。

# Generate XML from a local CSV
docker run --rm -v "$PWD:/data" -w /data \
  ghcr.io/sebastienrousseau/pain001:latest \
  generate -t pain.001.001.09 -d payments.csv -o out/

# Launch the REST API
docker run --rm -p 8000:8000 \
  ghcr.io/sebastienrousseau/pain001:latest \
  serve --host 0.0.0.0 --port 8000

03. 受管控环境#

银行与资金管理环境通常禁止动态加载插件。针对这一场景提供两项控制:

  • PAIN001_DISABLE_PLUGINS=1 禁用所有第三方插件发现;仅运行内置加载器。
  • pain001 plugins list / pain001 plugins show <name> 让每个被发现的插件在首次使用前都可审计。

一切都在本地运行。套件中的任何包都不会向外发送数据或调用 SaaS API,支付数据只有在您自己发送时才会离开主机,例如使用 pain001 upload。


04. 三条命令生成首个文件#

pip install pain001
pain001 init pain.001.001.09 -o payments.csv   # then put your payments in it
pain001 -t pain.001.001.09 -d payments.csv --dry-run

--dry-run 会依据 JSON Schema、XSD 以及(配合 --scheme 时)您所指定支付系统的规则手册进行校验,而不写出任何输出。退出码 0 表示该文件通过了上述检查:模式校验,以及在选用时的清算规则手册校验。您银行自身的配置规范与渠道规则属于另一回事,仍需通过银行测试。去掉 --dry-run 即可写出 XML。

继续阅读技术参考了解每个标志与端点,或查看快速上手常见问题解决运营层面的疑问。