# xinxin-ca
**Repository Path**: chen_jialin123/xinxin-ca
## Basic Information
- **Project Name**: xinxin-ca
- **Description**: Xinxin CA 是电子签名系统的后端工程，基于 Java 17、Spring Boot 3.5、Spring Cloud / Spring Cloud Alibaba 和 yudao/ruoyi-vue-pro 体系改造，提供系统管理、基础设施、文件能力、AI 能力，以及 CA 证书、电子印章、签章、验签、时间戳和审计日志等能力。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 4
- **Forks**: 3
- **Created**: 2026-08-12
- **Last Updated**: 2026-09-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Xinxin CA 后端服务
Xinxin CA 是电子签名系统的后端工程，基于 Java 17、Spring Boot 3.5、Spring Cloud / Spring Cloud Alibaba 和 yudao/ruoyi-vue-pro 体系改造，提供系统管理、基础设施、文件能力、AI 能力，以及 CA 证书、电子印章、签章、验签、时间戳和审计日志等能力。
## 系统仓库
| 仓库 | 内容 | 地址 |
| --- | --- | --- |
| Xinxin CA 后端 | Java 17 / Spring Cloud 后端、CA 核心服务、数据库脚本和文档 | [chenjialin-suod/xinxin-ca](https://github.com/chenjialin-suod/xinxin-ca) |
| Xinxin CA Web | Vue 管理后台，覆盖认证、证书、印章、签章、验签和审计 | [chenjialin-suod/xinxin-ca-web](https://github.com/chenjialin-suod/xinxin-ca-web) |
| Xinxin CA App | Expo/React Native App 与 Express BFF，覆盖认证、证书、印章、扫码签署和授权 | [chenjialin-suod/xinxinca-app-react](https://github.com/chenjialin-suod/xinxinca-app-react) |
| OFD Studio | 可独立运行的 OFD 结构化编辑平台，提供解析、编辑、转换、提取、结构检查与签名验证 | [chenjialin-suod/ofd-studio](https://github.com/chenjialin-suod/ofd-studio?tab=readme-ov-file) |
本地开发时各仓库建议放在同一父目录，例如 `D:\Project\ca-ehs\xinxin-ca`、`D:\Project\ca-ehs\xinxin-ca-web`、`D:\Project\ca-ehs\xinxin-app` 和 `D:\Project\ca-ehs\ofd-studio`。OFD Studio 是从业务系统抽离的独立项目，可单独运行或通过 HTTP/Java 服务集成；其 Apache License 2.0 与本仓库的非商业许可相互独立。
前端默认通过网关访问后端服务：
```text
http://127.0.0.1:48080/admin-api
```
## 文档导航
| 文档 | 内容 |
| --- | --- |
| [文档中心](docs/README.md) | 全部项目文档入口 |
| [系统说明](docs/ca/system-overview.md) | 系统边界、架构、核心对象和业务流程 |
| [接口参考](docs/ca/api-reference.md) | 后台、CA App 和 App BFF 接口目录及请求规范 |
| [操作手册](docs/ca/operation-guide.md) | 认证、证书、印章、授权、签署和验签操作 |
| [部署与数据库](docs/ca/deployment-and-database.md) | 启动、配置、验证、数据库备份与恢复 |
| [电子签名文件合规标准](docs/contract/electronic-signature-file-compliance-standard.md) | 签名文件、证据链和合规要求 |
| [许可协议与商业授权](docs/license-and-commercial-authorization.md) | 非商业许可范围、商业使用判断和授权申请方式 |
## 系统截图
以下截图展示当前电子签名系统的主要功能。截图中的组织、用户、证书、文件、编号和统计数据均为演示环境示例，实际页面会根据版本、租户、角色权限和业务数据有所不同。
### 管理后台工作台
认证中心：组织认证与个人实名认证
#### 组织认证
组织认证支持主体资料、统一社会信用代码、法定代表人、管理员、企业印章绑定证书、申请材料和并行审核流程。
#### 个人实名认证
个人认证支持选择用户和证书，提交实名资料与身份证材料，并衔接活体认证、手机号认证和实名审核。
CA 与数字证书
#### CA 申请与信任链
支持根 CA、中间 CA 的申请、审核、签发和证书下载，并可建立 Adobe/WPS 原生验签所需的 RSA 信任链。
#### 数字证书申请
证书申请向导按应用场景选择 SSL/TLS、代码签名、客户端、S/MIME、IoT、电子签章等证书类型，并配置主体和算法后提交签发。
签名图片、电子印章与签署任务
#### 签名图片中心
统一管理本人签名图片和已授权签名，支持新增、验证、下载、启停和默认签名设置。
#### 电子印章中心
集中展示印章统计、有效状态和最近动态，并提供印章模板、图片、授权、审批、权限、策略与生命周期管理。
#### 签署任务管理
支持查询 PDF/OFD 签署任务与算法、状态、截止时间，并进行详情查看、撤销和冻结等操作。
PDF 合同签署与 OFD 签署
#### PDF 合同签署
通过文件选择、本地上传或 OnlyOffice 在线编辑准备合同，再设置签署方、编排签署字段并发起流程。
#### OFD 签署工作台
OFD Studio 支持页面编辑、文字/图片/印章、验签、转换、结构查看与 OFD 文件导出。
移动 App：证书与在线签署
| 个人资料与证书 |
证书管理 |
 |
 |
| 选择签名、印章和证书 |
确认在线签署 |
 |
 |
## 技术栈
| 技术 | 版本/说明 |
| --- | --- |
| Java | 17 |
| Maven | 3.8+ |
| Spring Boot | 3.5.9 |
| Spring Cloud | 2025.x |
| Spring Cloud Alibaba | 2025.x |
| Nacos | 注册中心 / 配置中心 |
| MyBatis-Plus | ORM 与 Mapper 基础能力 |
| Redis / Redisson | 缓存、分布式锁 |
| Spring Security | 登录认证与权限控制 |
| Spring Cloud Gateway | 网关模块 |
| Bouncy Castle | CA/证书/国密相关能力 |
| OFDRW | OFD 文档处理与签章 |
## 所需软件
### 必装软件
| 软件 | 建议版本 | 用途与检查命令 |
| --- | --- | --- |
| Git | 2.40+ | 获取代码；`git --version` |
| JDK | 17 LTS | 编译和运行后端；`java -version` |
| Maven | 3.8+ | 构建 Maven 多模块；`mvn -version` |
| MySQL Server/Client | 8.0+ | 业务数据库及全量 SQL 导入；`mysql --version` |
| Redis | 6.0+ | 缓存、认证状态、验证码、签署二维码会话；`redis-cli ping` |
| Nacos | 3.x | 服务注册发现和配置中心；默认控制台 `http://127.0.0.1:8848/nacos` |
| Node.js | 管理端使用 22.18+；App 建议 22 LTS | 前端、Expo 和 Express BFF；`node --version` |
| pnpm | 管理端 11.2.2；App 9.x | 安装和构建前端依赖；`pnpm --version` |
管理端与 App 使用不同 pnpm 主版本。建议通过 Corepack 或 Volta 按仓库 `packageManager` 字段切换，不要用一个全局版本强行覆盖两个仓库：
```bash
# xinxin-ca-web
corepack use pnpm@11.2.2
# xinxin-app
corepack use pnpm@9.0.0
```
如果 Windows PowerShell 阻止执行 `pnpm.ps1`，可直接使用 `pnpm.cmd`，或在符合组织安全策略的前提下调整当前用户的脚本执行策略。
### 推荐开发工具
| 软件 | 用途 |
| --- | --- |
| IntelliJ IDEA 2024+ | 导入根 `pom.xml`、运行 Spring Boot 服务和管理多启动配置 |
| VS Code | 管理 `xinxin-ca-web` 和 `xinxin-app` |
| Navicat / DataGrip / MySQL Workbench | 数据库查看和只读检查；全量恢复仍建议使用 MySQL CLI |
| RedisInsight | 查看 Redis 数据库和排查二维码/验证码状态 |
| Postman / Apifox | 接口联调；也可使用服务自带 Swagger/Knife4j |
| Nginx | 生产环境托管管理端静态文件、HTTPS 和 `/admin-api` 反向代理 |
### 按功能选装
| 软件/服务 | 何时需要 |
| --- | --- |
| OnlyOffice Document Server | 在线编辑 Office 合同并转换为 PDF |
| CA/TSA 服务商或本地 OpenSSL 能力 | 正式证书签发、吊销、时间戳和外部信任链 |
| 短信供应商 | 正式手机号认证；当前固定验证码只能用于演示 |
| 人脸核身/活体 SDK | 正式生物认证；当前自拍照流程只能用于演示 |
| MinIO、S3 或其他文件存储 | 保存合同、证书、签名图片、印章和已签文件 |
| RabbitMQ/RocketMQ/Kafka | 启用了对应消息功能时安装，核心 CA 本地联调可按配置关闭未使用实现 |
| Qdrant/Milvus | 启动 AI 向量能力时需要，纯 CA 部署可不启动 AI 模块 |
本地开发配置位于各 `*-server/src/main/resources/application-*.yaml`，CA 核心服务的本地配置为 `xinxin-module-ca/xinxin-module-ca-server/src/main/resources/application-local.yaml`。
默认本地依赖：
| 服务 | 默认配置 |
| --- | --- |
| MySQL | `127.0.0.1:3306/xinxinca` |
| Redis | `127.0.0.1:6379` |
| Nacos | `127.0.0.1:8848` |
| RocketMQ | `127.0.0.1:9876` |
| RabbitMQ | `127.0.0.1:5672` |
| Kafka | `127.0.0.1:9092` |
## 快速开始
以下步骤面向 Windows + IntelliJ IDEA 本地开发。更完整的生产部署、安全配置和数据库恢复说明见[部署与数据库教程](docs/ca/deployment-and-database.md)。
### 0. 检查目录与依赖
三个仓库建议放在同一父目录：
```text
D:\Project\ca-ehs\
├─ xinxin-ca\ 后端
├─ xinxin-ca-web\ 管理端
└─ xinxin-app\ Expo App + Express BFF
```
确认 JDK、MySQL、Redis、Nacos、Node.js 和 pnpm 已就绪，再启动业务服务。
### 1. 初始化数据库
全新环境导入当前完整快照：
```text
sql/mysql/xinxinca_full.sql
```
该脚本包含 `DROP DATABASE` 和导出时的现有数据，导入会覆盖同名库。详细步骤和校验值见 `sql/mysql/README.md`。
PowerShell 导入示例：
```powershell
& 'C:\Program Files\MySQL\MySQL Server 8.0\bin\mysql.exe' `
-u root -p `
-e "source D:/Project/ca-ehs/xinxin-ca/sql/mysql/xinxinca_full.sql"
```
### 2. 检查本地配置
网关默认端口：
```yaml
server:
port: 48080
```
CA 核心服务本地数据源在 `xinxin-module-ca/xinxin-module-ca-server/src/main/resources/application-local.yaml`：
```yaml
spring:
datasource:
dynamic:
datasource:
master:
url: jdbc:mysql://127.0.0.1:3306/xinxinca
username: root
password: ${MYSQL_PASSWORD}
```
CA 独立服务 `local` profile 默认端口为 `48083`。
### 3. 启动后端服务
当前根 POM 不包含 `xinxin-server` 聚合模块，按需启动 system、infra、CA、CA App 和网关：
```bash
mvn -pl xinxin-module-system/xinxin-module-system-server -am spring-boot:run
mvn -pl xinxin-module-infra/xinxin-module-infra-server -am spring-boot:run
mvn -pl xinxin-module-ca/xinxin-module-ca-server -am spring-boot:run
mvn -pl xinxin-module-ca-app/xinxin-module-ca-app-server -am spring-boot:run
mvn -pl xinxin-gateway -am spring-boot:run
```
使用 IntelliJ IDEA 时：
1. 选择“打开”并打开 `xinxin-ca/pom.xml`，等待 Maven 索引完成。
2. Project SDK 选择 Java 17，Maven Runner 的 JRE 同样选择 Java 17。
3. 分别创建 Spring Boot 运行配置：`SystemServerApplication`、`InfraServerApplication`、`CaServerApplication`、`CaAppServerApplication`、`GatewayServerApplication`。
4. 按上述顺序启动；CA Server 使用仓库默认 `local` profile，其余使用各自默认 profile。
5. 确认端口依次为 `48081`、`48082`、`48083`、`48084`、`48080`，并在 Nacos 控制台看到健康实例。
### 4. 启动前端
```bash
cd D:\Project\ca-ehs\xinxin-ca-web
pnpm.cmd install --frozen-lockfile
pnpm dev:antd
```
前端默认地址：
```text
http://localhost:5666
```
开发配置位于 `xinxin-ca-web/apps/web-antd/.env.development`，默认把 `/admin-api` 请求发送到 `http://127.0.0.1:48080`。
### 5. 启动 App 与 BFF
```bash
cd D:\Project\ca-ehs\xinxin-app
pnpm.cmd install --frozen-lockfile
pnpm.cmd dev
```
Windows 开发脚本默认启动：
- Expo Web：`http://127.0.0.1:5000`；
- Express BFF：`http://127.0.0.1:9091`；
- BFF 上游：网关 `48080`、CA App 服务 `48084`。
`pnpm dev` 会清理占用 `5000` 和 `9091` 的旧进程，运行前不要在这两个端口放置其他重要服务。
### 6. 本地部署验证
1. 打开 `http://127.0.0.1:48083/swagger-ui` 和 `http://127.0.0.1:48084/swagger-ui`。
2. 打开管理端 `http://localhost:5666`，确认能登录并看到 CA 菜单。
3. 打开 App `http://127.0.0.1:5000`，确认 BFF 请求没有返回 502。
4. 检查组织、证书、印章和签署数据能正常查询。
5. 使用测试文件完成一次签署、下载和验签，并核对审计与证书使用记录。
## 常用命令
| 命令 | 说明 |
| --- | --- |
| `mvn clean install` | 编译并安装全部模块 |
| `mvn clean package -DskipTests` | 跳过测试打包全部模块 |
| `mvn -pl xinxin-module-system/xinxin-module-system-server -am spring-boot:run` | 启动系统服务 |
| `mvn -pl xinxin-module-infra/xinxin-module-infra-server -am spring-boot:run` | 启动基础设施服务 |
| `mvn -pl xinxin-gateway -am spring-boot:run` | 启动网关 |
| `mvn -pl xinxin-module-ca/xinxin-module-ca-server -am spring-boot:run` | 启动 CA 独立服务 |
| `mvn -pl xinxin-module-ca-app/xinxin-module-ca-app-server -am spring-boot:run` | 启动 CA App 服务 |
| `mvn -pl xinxin-module-ca -am test` | 运行 CA 模块测试 |
## 项目结构
```text
xinxin-ca
├─ xinxin-dependencies/ # Maven BOM 与依赖版本管理
├─ xinxin-framework/ # 框架与 starter
│ ├─ xinxin-common/ # 通用工具、基础类型、异常、分页等
│ ├─ xinxin-spring-boot-starter-web/
│ ├─ xinxin-spring-boot-starter-security/
│ ├─ xinxin-spring-boot-starter-mybatis/
│ ├─ xinxin-spring-boot-starter-redis/
│ ├─ xinxin-spring-boot-starter-rpc/
│ ├─ xinxin-spring-boot-starter-mq/
│ ├─ xinxin-spring-boot-starter-monitor/
│ ├─ xinxin-spring-boot-starter-protection/
│ ├─ xinxin-spring-boot-starter-excel/
│ ├─ xinxin-spring-boot-starter-env/
│ ├─ xinxin-spring-boot-starter-biz-tenant/
│ ├─ xinxin-spring-boot-starter-biz-data-permission/
│ └─ xinxin-spring-boot-starter-biz-ip/
├─ xinxin-gateway/ # Spring Cloud Gateway
├─ xinxin-module-system/ # 系统管理模块
├─ xinxin-module-infra/ # 基础设施、文件、日志、代码生成等
├─ xinxin-module-ai/ # AI 对话、模型、知识库等
├─ xinxin-module-ca/ # CA 证书、电子印章、签章、验签等
├─ xinxin-module-ca-app/ # 面向 App 的认证、证书、印章、签署和授权入口
├─ docs/ # 系统、接口、操作、运维和合规文档
├─ sql/mysql/ # 数据库脚本
└─ pom.xml # 根 POM
```
## 模块说明
### xinxin-gateway
网关模块，基于 Spring Cloud Gateway WebFlux，可用于统一入口、路由转发、服务发现和接口文档聚合。
### xinxin-module-system
系统管理模块，包含用户、角色、菜单、部门、岗位、租户、字典、通知、短信、邮件、OAuth2、登录日志、操作日志等能力。
### xinxin-module-infra
基础设施模块，包含参数配置、文件上传、文件配置、API 日志、Redis 监控、代码生成、OFD 支持等能力。
### xinxin-module-ai
AI 能力模块，包含 AI 对话、模型管理、知识库、向量检索、Agent 等能力。
### xinxin-module-ca
CA 业务模块，提供证书、电子印章、签章、验签、时间戳、审计日志、第三方 CA provider 对接等能力。
### xinxin-module-ca-app
CA App 服务模块，提供用户认证状态、个人资料、证书申请、个人印章、签名图片、扫码签署、签署任务和用户授权等移动端业务入口。App BFF 默认直连其 `/app-api` 和 `/admin-api`，本地端口为 `48084`。
## 核心业务功能
| 功能域 | 主要能力 | 典型入口 |
| --- | --- | --- |
| 身份与组织认证 | 实名认证、生物活体检测、手机号短信核验、企业认证、法定代表人确认 | 管理端“组织管理”，App 认证流程 |
| 证书管理 | CA 层级、申请审核、签发、下载、续期、冻结、解冻、吊销、过期同步和归档 | 管理端“证书管理”，App“我的证书” |
| 电子印章 | 模板、图片、制作、启停、冻结、注销、授权、用印审批、权限和使用策略 | 管理端“电子印章”，App“我的印章” |
| 电子签名 | 个人签名图片、PDF/OFD 签章、合同签署、扫码签署和签署任务 | 管理端“PDF/OFD 签章、签署中心”，App“签署” |
| 用户授权 | 签署授权、登录授权、授权接受/拒绝/撤销、代办登录和授权证据 | App“授权管理”，管理端授权记录 |
| 验签与时间戳 | 文件验签、印章验证、时间戳创建/验证、信任锚下载 | 管理端“验签管理、时间戳” |
| 证据与审计 | 签署记录、证书使用记录、授权书 PDF、证据链和业务审计 | 管理端“签署记录、审计日志” |
| 服务商接入 | 第三方 CA/TSA 配置、健康检查和统一适配 | 管理端“CA 服务商” |
### 电子签名与合同签署
系统同时支持直接文件签章和多方合同工作流：
- 支持 PDF、OFD 文件签章，PDF 支持指定页、最后一页和骑缝章。
- 支持 `SM3withSM2` 和 `SHA256withRSA` 签名算法；具体选择应与证书密钥类型、信任链和阅读器兼容要求一致。
- 签署外观可使用个人签名图片、个人印章或企业印章，并可设置页码、坐标、宽高、原因和地点。
- 合同可配置签署人、签署字段、截止时间和顺序/并行签署模式；Office 文件可通过 OnlyOffice 编辑并转换为 PDF。
- 管理端可创建二维码签署会话，App 扫码后展示任务和文件预览，再完成或拒绝签署。
- 签署前服务端校验证书、印章、授权、租户、任务状态和签署密码；客户端必须明确确认签署意愿。
- 签署密码支持临时公钥加密传输，签署请求可记录客户端确认时间、设备标识和设备信息。
- 重要文件可附加可信时间戳；签署结果会形成签署记录、证书使用记录和审计证据。
典型合同流程：上传/编辑文件 → 配置签署人和字段 → 发起合同 → 生成签署任务 → 管理端或 App 完成签署 → 下载已签文件 → 验签和审计。
主要管理接口前缀：`/admin-api/ca/contract/**`、`/admin-api/ca/sign/**`；App 任务接口前缀：`/admin-api/ca-app/auth/sign-**`。字段级定义见[接口参考](docs/ca/api-reference.md)。
### 用户授权与印章授权
系统区分“用户授权”和“印章授权”，二者不能相互替代：
| 授权类型 | 作用 | 关键控制 |
| --- | --- | --- |
| 签署授权（`authType=1`） | 委托受托人在授权范围内处理签署业务 | 实名主体、有效期、证书/签名、签署意愿、受托人接受、时间戳和授权证据 |
| 登录授权（`authType=2`） | 允许受托人在有效期内进入授权代办上下文 | 委托人与受托人、租户、有效期、授权状态和代办登录校验 |
| 印章授权 | 授予指定用户使用某枚印章的资格 | 印章状态、授权范围、授权期限、审批状态、权限和使用策略 |
用户可查看“我发出的”和“我收到的”授权。单次用户授权最长 365 天；系统支持接受、拒绝、撤销和有效授权校验，并可生成、下载和验证授权书 PDF。授权不会共享委托人的登录密码、签署密码或 Token，实际业务仍会再次校验租户、资源状态和权限。
印章授权还会与用印审批、使用人权限和印章策略共同生效：拥有一条授权记录并不代表可以绕过审批或使用被冻结、停用、过期、注销的印章。
### 生物认证与短信认证
个人身份认证当前按固定顺序推进：
```text
实名认证 realName
→ 生物活体认证 liveness
→ 手机号短信认证 mobile
→ 全部完成 complete
```
`GET /admin-api/ca-app/auth/status` 返回三类原始状态、`realNameAuthenticated`、`faceAuthenticated`、`mobileAuthenticated`、汇总字段 `allAuthenticated` 以及下一步 `nextStep`。App 应根据服务端状态跳转，不能仅用本地页面记录认定认证已经完成。
生物认证当前以人脸活体为入口：
- `POST /admin-api/ca-app/auth/liveness/complete` 接收活体流水号、人脸图片地址、核身结果、结果签名、活体分数、人脸相似度和错误信息。
- 当前代码支持自拍照演示，并预留正式人脸核身 SDK 的返回字段；正式上线前必须改成服务端向生物认证供应商查询或验签，不能信任客户端直接提交的 `isSuccess`、分数或图片结论。
- 生物认证结果应绑定用户、租户、实名认证身份、一次性流水号、认证场景、设备和有效时间，并防止流水号重放。
- 原始人脸图片、生物模板和供应商原始响应属于高度敏感个人信息，应最小化采集、加密存储、限制访问、设置保留期限并记录授权同意；普通接口和日志不应返回完整材料。
- 后续可扩展动作活体、静默活体、证件照人脸比对、风险分级、失败重试限制、多供应商路由和人工复核。高风险签署可在签署意愿确认阶段触发二次活体认证。
短信认证使用“发送验证码 + 校验验证码”两步：
- `POST /admin-api/ca-app/auth/mobile/send-code` 接收待认证手机号并触发验证码发送。
- `POST /admin-api/ca-app/auth/mobile/verify` 校验手机号与验证码，成功后更新当前用户的手机号和认证状态。
- 当前短信供应商尚未正式接入，演示环境使用固定验证码 `123456`。该行为只能用于本地演示，生产部署前必须移除固定验证码并接入系统短信能力或合规供应商。
- 正式实现应使用随机一次性验证码，设置短有效期、使用后立即失效，并对手机号、账号、设备和 IP 设置发送间隔、日限额、错误次数及临时锁定。
- 验证码应以不可逆摘要或受保护形式保存，不得写入应用日志；接口响应不应暴露验证码或区分“手机号是否已注册”等可被枚举的信息。
- 发送和校验均需保留脱敏审计流水，包括场景、供应商消息 ID、结果、时间、设备与风险信息，但不保存短信正文和明文验证码。
后续认证能力建议通过统一认证流水和策略编排扩展，而不是把供应商逻辑写入 Controller：
| 能力 | 建议补充 |
| --- | --- |
| 生物认证供应商 | 建立适配器接口，支持初始化、结果查询、回调验签、超时和降级 |
| 短信供应商 | 复用系统短信渠道和模板，记录发送流水、供应商回执及失败重试 |
| 风险控制 | 结合账号、手机号、设备、IP、地理位置和行为频率决定验证码/活体强度 |
| 认证证据 | 保存策略版本、用户同意、认证流水、可信时间和结果摘要，支持审计验证 |
| 场景复用 | 覆盖首次开户、修改手机号、证书签发、找回密码、授权、敏感签署和风险复核 |
| 隐私治理 | 明示目的和期限，支持撤回授权、到期删除、脱敏查询和最小权限访问 |
App BFF 对应路径为 `/api/app-auth/liveness/complete`、`/api/app-auth/mobile/send-code` 和 `/api/app-auth/mobile/verify`。正式接入第三方能力时，客户端只负责拉起 SDK 和提交一次性凭据，最终认证结论必须由服务端生成。
### CA 证书管理
系统支持根证书、中间证书、服务器证书、客户端证书、代码签名证书、电子邮件证书、IoT 设备证书、mTLS 证书、OCSP 签名证书、TSA 证书和电子印章证书。
证书生命周期为：
```text
申请 APPLIED
→ 待审核 PENDING_REVIEW
→ 已批准 APPROVED
→ 已签发 ISSUED
→ 已激活 ACTIVE
→ 冻结/解冻、续期、吊销、过期或归档
```
其中 `ACTIVE` 证书可参与正常签署；`FROZEN`、`REVOKED`、`EXPIRED`、`ARCHIVED` 等状态不能作为有效签署凭据。续期会生成新的有效材料，历史证书及其签署证据仍需保留。删除证书前会检查签署、印章和使用记录等依赖，生产数据更适合吊销或归档。
证书模块还提供证书链、信任锚、证书下载、使用记录、设备证书和第三方服务商签发/验证能力。私钥和原始密钥材料不得出现在前端、日志、README 或公开仓库中。
### 电子印章管理
支持公章、财务章、合同章、发票章、法人章、部门章、个人章、电子印章、个人签名、骑缝章、日期章和自定义章。
印章完整流程包括：
1. 维护印章模板和图片规格。
2. 创建草稿或提交申请，绑定所属主体、证书和印章类型。
3. 审核并制作印章，维护印章图片并设置主图。
4. 启用印章，配置授权、用印审批、使用人权限和使用策略。
5. 在合同或文件签章中使用，并记录每次用印和证书使用情况。
6. 根据风险或主体变化执行停用、冻结、解冻、注销或到期处理。
印章状态包括草稿、审核中、已制作、待启用、已启用、已停用、已冻结、已注销和已过期。只有状态、证书、授权、审批、权限及策略全部满足时才允许用印，所有状态变化都会保留生命周期记录。
### 验签、可信时间与审计
- 文件验签会检查文件完整性、签名值、签名算法、签署证书、证书链、证书状态、电子印章和时间戳。
- 时间戳服务支持创建、验证和状态检查，用于证明目标数据在特定可信时间已经存在。
- 信任锚接口用于查询或下载验证所需的根证书/信任材料。
- 审计内容覆盖认证审核、证书生命周期、印章生命周期、授权、合同任务、签署、验签和服务商调用。
- 日志和证据中应保存可追踪的业务编号、任务编号、证书编号和时间信息，但必须对个人信息、Token、密码、私钥及服务商凭据进行保护。
## 符合的标准与规范
Xinxin CA 按电子签名、PKI、版式文件和可信时间相关标准设计。下表描述的是**当前代码与标准的技术映射**，其中“已实现”表示已经具备对应的数据结构、协议或校验逻辑，并不等同于已经取得行政许可、产品认证、商用密码检测、等保测评或第三方符合性证书。
| 分类 | 标准或规范 | 当前实现 | 状态 |
| --- | --- | --- | --- |
| 法律框架 | [《中华人民共和国电子签名法》](https://www.miit.gov.cn/jgsj/zfs/fl/art/2022/art_e3f623f70c23497e88a941170093446a.html) | 通过实名认证、签署意愿确认、证书与私钥控制、文件摘要、签后完整性检查、可信时间和审计证据，对可靠电子签名的身份、控制、改动可发现和数据可调取要求进行工程映射 | 设计对齐；最终法律效力取决于实际业务、部署控制、证据质量和司法/第三方认定 |
| 电子认证服务 | [《电子认证服务管理办法》](https://www.miit.gov.cn/zcfg/xxtxl/art/2015/art_cd7d7793ea154255b1f7b3d3a07ff2a0.html) | 提供 CA 层级、证书申请审核、签发、冻结、吊销、归档、服务商适配和审计能力 | 软件能力已实现；对外提供法定电子认证服务时仍须使用具备相应资质的机构和设施 |
| PDF 版式 | [ISO 32000-2:2020（PDF 2.0）](https://www.iso.org/standard/75839.html) | 使用标准 AcroForm 字段树、Widget、签名字典、ByteRange 和增量修订组织签署字段与多方签名 | 已实现 PDF 签名相关子集 |
| PDF 高级签名 | [ETSI EN 319 142-1（PAdES）](https://www.etsi.org/deliver/etsi_EN/319100_319199/31914201/01.02.01_60/en_31914201v010201p.pdf) | 支持 PDF ByteRange、detached CMS/CAdES、`SigningCertificateV2`、证书链嵌入、签后自检和多签名增量保存 | 基础签名能力已实现；PAdES-B-T/B-LT 等具体等级须结合 TSA、OCSP/CRL、DSS/VRI 和兼容性测试验收 |
| 密码消息 | [RFC 5652（CMS）](https://www.rfc-editor.org/rfc/rfc5652.html) | 使用 CMS/PKCS#7 SignedData 承载 detached 签名，并支持签名值、摘要和证书链验证 | 已实现核心签名与验签能力 |
| PKI 证书 | [RFC 5280（X.509 PKIX）](https://www.rfc-editor.org/rfc/rfc5280.html) | 支持根 CA、中间 CA、终端实体证书、证书链、用途、有效期及吊销状态等生命周期数据 | 证书链模型已实现；生产信任策略、CRL/OCSP 和根证书分发须按环境配置 |
| 可信时间 | [RFC 3161（Time-Stamp Protocol）](https://www.rfc-editor.org/rfc/rfc3161.html) | 支持时间戳请求、Token 解析、TSA 证书和消息摘要校验，并提供 OpenSSL TSA 适配器 | 按配置支持；正式业务必须连接可独立验证的真实 TSA |
| 国密时间戳 | [GM/T 0033-2023《时间戳接口规范》](https://std.samr.gov.cn/hb/search/stdHBDetailed?id=1BF26B7AA006FD76E06397BE0A0A81D8) | 时间戳服务和服务商适配层预留国密 TSA 接口与校验路径 | 按服务商配置与联调验收 |
| 国密算法 | SM2/SM3 算法体系 | 支持 `SM3withSM2` 证书与签名，并与 RSA/SHA-256、ECDSA 形成多算法能力 | 软件算法能力已实现；受监管生产场景应使用经检测认证的密码模块、密码机或云密码服务 |
| OFD 版式 | [GB/T 33190-2016《电子文件存储与交换格式 版式文档》](https://openstd.samr.gov.cn/bzgk/std/newGbInfo?hcno=3AF6682D939116B6F5EED53D01A9DB5D) | 已提供 OFD 文件入口、编辑界面、格式识别以及 OFD-SES/OFD-ESL 扩展模型 | 部分支持；真实 OFD 数字签章引擎尚未接入，系统会明确失败而不会生成占位签名 |
| 阅读器兼容 | Adobe Acrobat / WPS 原生验签 | PDF 使用 `adbe.pkcs7.detached`、完整 RSA/SHA-256 证书链和标准签名域，并提供国密证书到 PDF 伴生 RSA 证书的选择路径 | 已具备互操作基础；须完成企业信任根安装及目标版本联合验收 |
生产上线时建议将标准符合性拆成“文件格式”“密码实现”“身份与意愿”“密钥专有控制”“可信时间”“证书状态”“证据保全”“第三方互操作”八个维度分别验收。系统通过 `formalComplianceReady` 对正式文件实施统一准入：TSA、可信密钥设施、长期验证材料、不可篡改存储等关键能力未就绪时，只能作为技术测试文件，不能把占位能力或普通服务器时间声明为正式合规能力。
更详细的控制项、验收清单和当前差距见[电子签名文件合规标准](docs/contract/electronic-signature-file-compliance-standard.md)与[Adobe/WPS 原生验签操作指南](docs/contract/adobe-wps-native-signing-operation-guide.md)。
## 技术创新点
以下内容属于本项目的工程特色和组合创新，不作“行业首创”声明：
1. **国密与国际算法双栈。** 同一平台统一管理 SM2/SM3、RSA/SHA-256 和 ECDSA 证书与签名能力，可根据文件格式、证书密钥类型、信任环境和阅读器兼容要求选择算法。
2. **同一身份的 PDF 伴生证书路由。** 用户在 App 中可以保留国密个人证书；进入 Adobe/WPS PDF 场景时，系统可选择或补发同一实名身份、同一企业信任体系下的 RSA 伴生证书，兼顾国密业务与通用阅读器验签。
3. **原生 PDF 数字签名而非图片盖章。** 签名图片和印章只负责可视外观，文件真实性由 AcroForm 签名域、ByteRange、CMS 签名值、证书链和增量修订保护；签后改写能够被密码学验签发现。
4. **“合规能力硬门禁”设计。** 系统在发起、签署、验签和授权书生成阶段统一计算 `formalComplianceReady`。真实 TSA、密钥保护或证据保全未就绪时直接降级为技术测试或阻止生成，避免用占位字符串、伪时间戳或空签名冒充成功。
5. **管理端编排、移动端确认的签署闭环。** 管理端负责文档准备、签署人、顺序和字段位置，App 通过扫码获取一次性任务，展示文件与签署内容并以签署密码完成意愿确认；后续可按风险策略叠加生物认证或短信认证。
6. **证书、印章、授权和策略四层校验。** 一次签署不仅检查用户权限，还联合检查证书状态、印章生命周期、用户/印章授权、用印审批、使用次数、期限、部门和合同分类策略，降低“有菜单权限即可用印”的风险。
7. **逐业务证据链。** 对原始文件、表单版、签后文件、CMS、证书、签署人、任务、设备、意愿确认和可信时间分别留存摘要与关联编号，并支持以前序摘要串联业务证据，便于独立验签、追溯和后续接入存证服务。
8. **失败关闭和反占位机制。** 对尚未接入的真实 OFD 签章、不可用 TSA 或无法验证的签后文件明确返回失败，不产生“看起来已签”的占位成果，防止测试能力误入正式业务。
9. **统一服务商适配层。** 本地 CA、OpenSSL TSA 和第三方 CA/TSA 通过统一 provider 接口接入，业务层不绑定单一厂商，可实施健康检查、路由、替换、故障隔离和分环境配置。
10. **全生命周期与多租户一体化。** 将组织认证、个人实名、CA 层级、证书、印章、合同、授权、签署、验签和审计放在同一租户与数据权限体系内，状态变化和关键操作均能关联到业务主体与操作人。
## CA 模块索引
CA 后端路径：
```text
xinxin-module-ca
├─ xinxin-module-ca-api/ # 对外 API、DTO、枚举、Feign 契约
└─ xinxin-module-ca-server/ # CA 业务实现
```
核心入口：
```text
xinxin-module-ca/xinxin-module-ca-server/src/main/java/cn/start/xinxin/module/ca/CaServerApplication.java
```
核心目录：
```text
xinxin-module-ca/xinxin-module-ca-server/src/main/java/cn/start/xinxin/module/ca
├─ api/ # API 实现，例如 CertificateApiImpl
├─ controller/admin/ # 管理端 REST Controller
├─ service/ # 业务服务
├─ dal/dataobject/ # MyBatis-Plus DO
├─ dal/mysql/ # Mapper
├─ convert/ # MapStruct 转换器
├─ framework/ # CA 模块局部框架配置
└─ enums/ # 服务端枚举
```
CA 管理端控制器：
```text
controller/admin/apply/CaInfoApplyController.java
controller/admin/audit/AuditLogController.java
controller/admin/authorization/UserAuthorizationController.java
controller/admin/ca/CaInfoController.java
controller/admin/cert/CertApplyController.java
controller/admin/organization/CaOrganizationController.java
controller/admin/profile/CaProfileController.java
controller/admin/provider/CaProviderController.java
controller/admin/seal/SealInfoController.java
controller/admin/sign/ContractWorkflowController.java
controller/admin/sign/SignatureController.java
controller/admin/tsa/TimestampController.java
controller/admin/verify/VerifyController.java
```
CA 业务服务：
```text
service/apply/CaInfoApplyService.java
service/audit/CaAuditLogService.java
service/authorization/UserAuthorizationService.java
service/ca/CaInfoService.java
service/cert/CertApplyService.java
service/crypto/CryptoKeyService.java
service/organization/CaOrganizationService.java
service/profile/SignPasswordService.java
service/provider/CaProviderService.java
service/seal/SealInfoService.java
service/sign/SignatureService.java
service/time/TrustedTimeService.java
service/tsa/TimestampService.java
service/verify/VerifyService.java
```
第三方 CA provider 适配器：
```text
service/provider/CaProviderAdapter.java
service/provider/AbstractCaProviderAdapter.java
service/provider/impl/BjcaProviderAdapter.java
service/provider/impl/CfcaProviderAdapter.java
service/provider/impl/DigicertProviderAdapter.java
service/provider/impl/GdcaProviderAdapter.java
service/provider/impl/GlobalsignProviderAdapter.java
service/provider/impl/NetsunProviderAdapter.java
service/provider/impl/ShcaProviderAdapter.java
service/provider/impl/WotongProviderAdapter.java
```
## 前后端接口对应
前端 CA API 目录：
```text
D:\Project\ca-ehs\xinxin-ca-web\apps\web-antd\src\api\ca
```
后端 CA Controller 目录：
```text
xinxin-module-ca/xinxin-module-ca-server/src/main/java/cn/start/xinxin/module/ca/controller/admin
```
常见对应关系：
| 前端目录 | 后端 Controller | 说明 |
| --- | --- | --- |
| `api/ca/apply` | `CaInfoApplyController` | CA 信息申请 |
| `api/ca/audit` | `AuditLogController` | 审计日志 |
| `api/ca/authorization` | `UserAuthorizationController` | 用户授权记录、证据和验证 |
| `api/ca/cert` | `CertApplyController` | 证书申请、签发、吊销、续期 |
| `api/ca/info` | `CaInfoController` | CA 信息管理 |
| `api/ca/organization` | `CaOrganizationController` | 组织资料、认证和组织印章 |
| `api/ca/profile` | `CaProfileController` | 个人证书、签署密码和信任锚 |
| `api/ca/provider` | `CaProviderController` | 第三方 CA provider |
| `api/ca/seal` | `SealInfoController` | 电子印章、授权、模板、策略 |
| `api/ca/sign` | `ContractWorkflowController`、`SignatureController` | 合同工作流、签署任务和 PDF/OFD 签章 |
| `api/ca/timestamp` | `TimestampController` | 时间戳 |
| `api/ca/verify` | `VerifyController` | 验签、验章 |
## 配置说明
### 网关
主要配置：
```text
xinxin-gateway/src/main/resources/application.yaml
xinxin-gateway/src/main/resources/application-dev.yaml
```
本地端口：
```yaml
server:
port: 48080
```
### CA 独立服务
主要配置：
```text
xinxin-module-ca/xinxin-module-ca-server/src/main/resources/application.yaml
xinxin-module-ca/xinxin-module-ca-server/src/main/resources/application-local.yaml
```
默认应用名与端口：
```yaml
spring:
application:
name: ca-server
server:
port: 48081
```
`local` profile 覆盖端口：
```yaml
server:
port: 48083
```
CA 自定义配置位于 `xinxin.ca`，包含 RootCA、IntermediateCA、证书有效期、CRL、审计哈希链、TSA、可信授时、证据链保留周期等配置。
## 开发约定
- Controller 放在 `controller/admin/`，请求/响应 VO 放在对应 `vo` 子目录。
- Service 接口与实现按业务域放在 `service/`。
- DO 放在 `dal/dataobject`，Mapper 放在 `dal/mysql`。
- 对象转换优先使用 `convert` 下的 MapStruct 转换器。
- 错误码统一维护在 `xinxin-module-ca-api/src/main/java/cn/start/xinxin/module/ca/enums/ErrorCodeConstants.java`。
- CA 枚举优先放在 `xinxin-module-ca-api`，方便前后端契约、RPC 和跨模块复用。
- 新增菜单或权限时，同步检查 `sql/mysql` 下的菜单脚本或后台菜单配置。
- 工作区里可能有他人未提交改动，提交前请先检查 `git status --short`。
## 常见问题
### 前端请求 404 或跨域
确认前端 `apps/web-antd/.env.development`：
```bash
VITE_BASE_URL=http://127.0.0.1:48080
VITE_GLOB_API_URL=/admin-api
```
并确认网关正在 `48080` 端口运行，system、infra 和 CA 服务已注册到 Nacos。
### 启动时报数据库连接失败
检查 MySQL 地址、库名、用户名和密码，默认配置在：
```text
xinxin-module-ca/xinxin-module-ca-server/src/main/resources/application-local.yaml
```
当前本地库名是 `xinxinca`。
### CA 页面没有菜单
确认已导入 `sql/mysql/xinxinca_full.sql`，并检查当前登录用户角色是否拥有对应菜单权限。
### 修改配置后不生效
本地配置会加载 `application-${spring.profiles.active}.yaml`，并可能从 Nacos 加载配置。修改本地 YAML 后需要重启服务；如果启用了 Nacos 配置，也要检查 Nacos 中同名配置是否覆盖了本地配置。
## 联系方式
如有部署、二次开发、接口联调或功能使用问题，可通过以下方式联系：
| 方式 | 联系信息 |
| --- | --- |
| 电话 | [17674011342](tel:17674011342) |
| 邮箱 | [1546830229@qq.com](mailto:1546830229@qq.com) |
| 微信 | 扫描下方二维码添加，备注“Xinxin CA” |
请勿通过公开 Issue、聊天截图或邮件正文发送生产 Token、数据库密码、签署密码、私钥、证书密钥材料以及未经脱敏的个人信息。
## 许可协议与商业授权
本项目公开源代码，当前版本采用自定义的[《Xinxin CA 源码开放非商业许可协议 1.0》](LICENSE)：
- 个人学习、非商业教学、非商业学术研究以及不进入生产环境的技术评估可免费使用。
- 企业内部生产部署、客户私有化交付、商业项目集成、SaaS/云服务、收费服务、转售、再许可或贴牌发行等商业使用，必须事先取得著作权人的书面商业授权。
- 复制、修改或非商业再分发时，必须保留版权声明、完整许可协议和项目来源，并标注修改内容。
- 第三方组件和本项目历史上已经按其他许可证合法发布的特定版本，继续适用各自原有许可证；当前及后续包含新 LICENSE 的版本按本协议执行。
由于限制商业用途，本项目准确的性质是“源码开放/源代码可用（source-available）”，而不是 [OSI 开源定义](https://opensource.org/osd)下允许不受用途限制商业使用的开源软件。授权场景、申请材料及边界详见[许可协议与商业授权说明](docs/license-and-commercial-authorization.md)。
商业授权请联系：电话 `17674011342`，邮箱 [1546830229@qq.com](mailto:1546830229@qq.com)，或扫描上方微信二维码并备注“Xinxin CA 商业授权”。电话、微信和口头沟通仅用于咨询，最终以能够识别被授权主体、版本、用途、期限和范围的授权合同、授权书或著作权人明确书面确认为准。
本软件按“原样”提供，不附带任何明示或默示担保；完整条款以仓库 [LICENSE](LICENSE) 为准。