China E-Port Data Signature

中国电子口岸（海口海关）报文加签推送应用. A free, open-source end-to-end signature solution for Chinese E-Port CEBXxxMessage and Customs 179 messages. Plug-and-play, no middleware required. Suitable for enterprise-grade e-commerce and trade.

---

Foreword | 前言

After nearly two years of open-source code maintenance and exploration, we have developed an all-in-one solution offering free, open and universal access for a wide range of businesses. The aim is to digitally sign and forward XML messages to the General Administration of Customs via China E-Port (HaiKou Customs), facilitating efficient cross-border e-commerce and import-export business.

经过近两年的开源代码维护和探索，我们终于开发出一站式免费解决方案，为更多企业提供快速接入和使用能力。项目旨在实现中国电子口岸（海口海关）总署XML 报文加签推送，助力跨境电商与进出口业务发展。

2023-07

本项目遵循 GNU 3.0 协议，测试用例中企业信息已获授权，企业调试时应将报文数据中涉及到的报文传输编码（DXPID）、copCode、copName、电商平台代码ebpCode等主体信息替换成企业在中国电子口岸后台注册的有效信息。

---

Features | 功能亮点

• 支持中国电子口岸 CEBXxxMessage 及 179 数据报文加签
• Plug-and-play，开箱即用，无需中间件，无需二次编译
• 支持 JSON 报文直推
• 加签失败邮件通知、支持企业微信、钉钉、飞书、Discord 等扩展告警
• U-Key 健康状态异常自动重启 WebSocket 客户端
• 支持 Docker 镜像部署 & Maven 数据模型集成

---

Usage Scenarios | 业务场景

• 进出口贸易、跨境电商、物流、外贸等企业数据上报
• 所有需向中国电子口岸或海关报送签名报文的企业系统

---

Quick Start | 快速使用

• 单体应用：直接下载 Releases
• 微服务：切换 feature_microservice 分支
• Docker 镜像：Docker Hub
• Java项目集成：使用 Maven 数据模型, Maven Integration

<dependency>
    <groupId>io.github.weasley-j</groupId>
    <artifactId>chinaport-data-signature-data-model</artifactId>
    <version>Latest Version</version>
</dependency>

建议 Windows 平台用 Git Bash 启动（终端日志不乱码）

---

功能概述

---

系统架构

---

报文加签推送流程

---

2022年2月14日之前互联网无相关资料，本项目填补空白。对比市场付费服务多数隐藏加签算法，完全开源，欢迎反馈贡献！

---

电子口岸支持覆盖范围

理论支持中国大陆各大地方电子口岸，表中为已验证/待验证端口：

电子口岸	是否支持	是否验证
海口电子口岸	✅	✅
广州电子口岸	✅	✅
郑州电子口岸	✅	待验证
上海电子口岸	✅	待验证
杭州电子口岸	✅	待验证
...

---

软件运行环境/开发环境

类目	版本	备注
JDK	Java SE Development Kit 17	Java SE Development Kit 17 +
硬件	Windows10/11/Server, Linux	u-key 仅支持插在 Windows 电脑
性能	≥1核CPU+2G内存	最低配置
技术要求	基本 shell 操作	Windows 需会安装 U-Key 并设置脚本

• 参见中国电子口岸C卡/Key客户端下载页面：卡介质登录
• 电子口岸的操作员 Ukey 图片资料

---

项目运行配置

本项目为 Spring Boot 应用，所有参数均支持yaml/properties配置，详见 配置样例

主要配置参数一览：

配置参数	必须	说明
eport.signature.algorithm	N	XML签名的算法类型，不指定时使用程序自动推断的算法, 推荐使用程序自动推断的算法
eport.signature.ukey.ws-url	Y	u-key所连接的Windows电脑的socket链接url,如: ws://127.0.0.1:61232,下载release直接运行的修改全局配置的UKEY_HOST即可
eport.signature.ukey.password	N	u-key密码的密码，默认: 88888888, 如果密码改过，需要指定下，下载release直接运行的修改全局配置的UKEY_PASSWORD即可
eport.signature.ukey.health.endpoint.client-name	N	Windows上重启的ukey可执行文件全限定文件名称，不指定将自动查找（将程序安装到Windows平台上会生效，Linux、Uni环境无效）
eport.signature.auth.enable	N	是否启用token鉴权，取值：on/off，生产环境建议开启
eport.signature.auth.token	N	客户端请求鉴权token, 默认值: DefaultAuthToken, 请求头，生产环境不建议使用默认值
eport.signature.report.ceb-message.cop-code	Y	电子口岸XML报文传输企业代码
eport.signature.report.ceb-message.cop-name	Y	传输企业名称，报文传输的企业名称
eport.signature.report.ceb-message.dxp-id	Y	文传输编号，向中国电子口岸数据中心申请数据交换平台的用户编号
eport.signature.report.ceb-message.server	N	海关服务器地址，缺省则采用Client中的密文作文默认Server URL
eport.signature.report.customs179.ebp-code	Y	海关 179 数据上报的电商平台代码
eport.signature.report.customs179.server	N	数据上报服务器URL地址，链接格式: https://域名联系海关/ceb2grab/grab/realTimeDataUpload，没有配置的话采用项目内置的URL密文地址

---

跨平台启动

Windows

• Git Bash 右键快捷启动脚本指南

Linux/MacOS

sh start.sh

参见start.sh

---

邮件通知/故障自愈

• 配置通知示例
• 支持异常自动重启、U-Key 自动健康检测
• 可拓展企业微信、钉钉、飞书、Discord等

---

接口调试及响应示例

• 启动项目并访问 http://localhost:8080
• 在线 H5 文档调试及参数说明，支持直接发起签名请求（注意请求参数的字符串转义）

XML加签响应示例：

{
  "message": "操作成功",
  "success": true,
  "timestamp": "2023-07-15 12:15:47",
  "code": 200,
  "data": {
    "success": true,
    "certNo": "03000000000cde6f",
    "x509Certificate": "MIIEoDCCBESgAwIBAgIIAwAAAAAM3m8wDAYIKoEcz1UBg3UFADCBmDELMAkGA1UEBhMCQ04xDzANBgNVBAgMBuWMl+S6rDEPMA0GA1UEBwwG5YyX5LqsMRswGQYDVQQKDBLkuK3lm73nlLXlrZDlj6PlsrgxGzAZBgNVBAsMEuivgeS5pueuoeeQhuS4reW/gzEtMCsGA1UEAwwk5Lit5Zu955S15a2Q5Lia5Yqh6K+B5Lmm566h55CG5Lit5b+DMB4XDTIzMDMyOTAwMDAwMFoXDTMzMDMyOTAwMDAwMFowVjELMAkGA1UEBhMCQ04xMzAxBgNVBAsMKua1t+WNl+ecgeiNo+iqiei/m+WHuuWPo+i0uOaYk+aciemZkOWFrOWPuDESMBAGA1UEAwwJ5p2o5aaC6YeRMFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE0vOQmplAr9igPZrA8F1msqnFd0U++6G6NhG5rNuIUWft0BwQn7eSJkt5/fvSSoe7pUg2/awHUWPnzkeeQc7oVqOCArUwggKxMBEGCWCGSAGG+EIBAQQEAwIFoDAOBgNVHQ8BAf8EBAMCBsAwCQYDVR0TBAIwADApBgNVHSUEIjAgBggrBgEFBQcDAgYIKwYBBQUHAwQGCisGAQQBgjcUAgIwHwYDVR0jBBgwFoAURCQxt0wEvoAVXmuo4N1bjKXTh0UwHQYDVR0OBBYEFAytGob5L0WqhOCZ5l6Lf2jUdNrAMGgGA1UdIARhMF8wXQYEVR0gADBVMFMGCCsGAQUFBwIBFkdodHRwczovL3d3dy5jaGluYXBvcnQuZ292LmNuL3RjbXNmaWxlL3UvY21zL3d3dy8yMDIyMDQvMTIxMzI5NDh4dDZwLnBkZjB/BgNVHR8EeDB2MHSgcqBwhm5sZGFwOi8vbGRhcC5jaGluYXBvcnQuZ292LmNuOjM4OS9jbj1jcmwwMzAwMDAsb3U9Y3JsMDAsb3U9Y3JsLGM9Y24/Y2VydGlmaWNhdGVSZXZvY2F0aW9uTGlzdD9iYXNlP2NuPWNybDAzMDAwMDA+BggrBgEFBQcBAQQyMDAwLgYIKwYBBQUHMAGGImh0dHA6Ly9vY3NwLmNoaW5hcG9ydC5nb3YuY246ODgwMC8wOgYKKwYBBAGpQ2QFAQQsDCrmtbfljZfnnIHojaPoqonov5vlh7rlj6PotLjmmJPmnInpmZDlhazlj7gwEgYKKwYBBAGpQ2QFAwQEDAIwMTAiBgorBgEEAalDZAUIBBQMEjUxMjMyNDE5NjQxMDE3Mjk3WDAgBgorBgEEAalDZAUJBBIMEDAzLUpKMEc5MDAyMjA3NTIwGQYKKwYBBAGpQ2QFCwQLDAlNQTVUTkZHWTkwEgYKKwYBBAGpQ2QFDAQEDAIwMDASBgorBgEEAalDZAIBBAQMAjEyMBIGCisGAQQBqUNkAgQEBAwCMTQwDAYIKoEcz1UBg3UFAANIADBFAiBM4OVAc8aaCZU4XFfcVMkC7bWIIenRnPLxrnwVeYO3CQIhANQ767YIurkJCoLtwyqQPbUZe/+3BjGZcIWqB1mAl9T+",
    "digestValue": "b2FtM/jHvW4fnJpMMPWk/177RwA=",
    "signatureValue": "Pa2Ge3A1iH9e+85jIraVccvf2MB4ykjgC1MjObNd/MbPOSZRWTaizlnfReH3ErRMH5Wc3m60ZM6h56v7t7lIWg==",
    "signatureNode": "<ds:SignedInfo xmlns:ceb=\"http://www.chinaport.gov.cn/ceb\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><ds:CanonicalizationMethod Algorithm=\"http://www.w3.org/TR/2001/REC-xml-c14n-20010315\"></ds:CanonicalizationMethod><ds:SignatureMethod Algorithm=\"http://www.w3.org/2000/09/xmldsig#sm2-sm3\"></ds:SignatureMethod><ds:Reference URI=\"\"><ds:Transforms><ds:Transform Algorithm=\"http://www.w3.org/2000/09/xmldsig#enveloped-signature\"></ds:Transform></ds:Transforms><ds:DigestMethod Algorithm=\"http://www.w3.org/2000/09/xmldsig#sha1\"></ds:DigestMethod><ds:DigestValue>b2FtM/jHvW4fnJpMMPWk/177RwA=</ds:DigestValue></ds:Reference></ds:SignedInfo>"
  }
}

海关 179 加签响应示例：

{
  "message": "操作成功",
  "success": true,
  "timestamp": "2023-07-15 12:16:36",
  "code": 200,
  "data": {
    "success": true,
    "certNo": "03000000000cde6f",
    "signatureValue": "pVWbjCXqCy2zk0RRqbw16hWZozjTSP444fdT2k5MjqigJDsLZ/Vfgout3o/Gg0WrPbJnH/2wlI8I0n3niqYiqw=="
  }
}

---

支持我们的项目

为什么赞助

• 帮助企业节约采购费用，使用行业通用开源加签
• 推动技术开放与协作，促进行业共享
• 支持项目持续改进和功能更新

为什么开源

• 市面绝大多数电子口岸加签解决方案为商业付费且封闭，企业投入成本高，透明度低。
• 我们坚信报文加签属于数字贸易的基础设施，应惠及更多企业与开发者。
• 开源不仅有助于提升行业信任度，也能集结社区力量持续改进和快速适配各地业务需求。
• 欢迎各类企业和个人贡献代码、文档、案例或提出宝贵建议！

如何赞助

• PayPal

---

感谢/接入企业名录

排名不分先后，自2023-07-11登记：

• 海南省荣誉进出口贸易有限公司 官网
• 广州市汇客物流有限公司
• 海南嗨亿购科技有限公司
• 小红书
• 广东铭鸿数据有限公司
• 海口中伟机免投资有限公司
• ...

---

License

GNU 3.0

---

任何问题欢迎提 issue 或发邮件至 julxxy@outlook.com 交流！