# TrustBox **Repository Path**: li-tongle/trust-box ## Basic Information - **Project Name**: TrustBox - **Description**: 统一密码库管理系统 - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-03 - **Last Updated**: 2026-05-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TrustBox TrustBox 是一个面向企业内部场景的敏感凭证管理平台，用于集中管理账号密码、Token、SSH Key 和其他 Secret，并提供访问控制、审计、版本追溯、MFA 二次校验、浏览器自动填充和集成接口授权能力。 项目当前采用前后端分离结构，包含后端服务、管理端前端、浏览器插件和 OpenSpec 协作文档。 ## 项目概览 - `backend`：Spring Boot 后端服务，负责认证鉴权、Secret 管理、审计、主数据维护、集成接口与个人模式数据源 - `frontend`：Vue 3 管理端，负责后台管理界面、权限路由、Secret 列表与详情交互 - `plugin`：浏览器自动填充插件，负责页面识别、凭证获取与表单填充 - `openspec`：需求变更、设计说明、任务拆解和规格文档 ## 核心能力 - Secret 全生命周期管理：创建、编辑、删除、查看、版本记录、版本回滚 - 敏感信息查看二次认证：支持基于 TOTP 的二次校验 - 权限与菜单控制：用户、角色、菜单、导航菜单、授权码控制 - 主数据维护：分类、环境、类型、用户等元数据管理 - 审计中心：记录登录、查看明文、删除、回滚、接口调用等关键操作 - 集成接口授权：支持 Access Key / Secret Key、签名验签、资源级授权、IP/Header 白名单免签旁路 - 个人模式：支持基于 SQLite 的本地数据目录 - 浏览器自动填充：通过插件为业务页面注入 Secret 自动填充能力 ## 技术栈 ### 后端 - Java 25 - Spring Boot 3.5.14 - Spring Web - Spring Security - Spring Validation - Spring Boot Actuator - Maven - MyBatis-Plus 3.5.15 - MySQL Connector/J - SQLite JDBC - Fesod Sheet 2.0.1-incubating - Lombok - 测试：Spring Boot Test、Spring Security Test、H2 ### 前端 - Vue 3.5 - TypeScript 6 - Vite 8 - Vue Router 4 - Pinia 3 - Element Plus 2 - Axios - QRCode ### 插件 - Chrome Extension Manifest - `background.js` 后台逻辑 - `content.js` 页面注入与表单交互 - `popup.html` / `popup.js` 插件弹窗 ### 构建与交付 - JVM 包：Spring Boot JAR - Native 包：GraalVM Native Image + `native-maven-plugin` - 前端静态资源：Vite 构建输出 ## 后端模块结构 后端代码位于 `backend/src/main/java/com/trustbox`，整体是比较清晰的分层结构。 ### 启动入口 - `TrustBoxApplication`：Spring Boot 启动类 ### DDD 树形结构 可以把后端理解成一家公司，分工从外到内依次是： - `interface_http`：前台 / 接待处，只负责接客，说人话，不负责懂业务 - `application`：项目经理 / 业务办公室，负责编排流程，指挥谁先做什么 - `domain`：业务专家 / 规则制定者，负责真正的业务判断和规则约束 - `infrastructure`：后勤 / IT / 仓库，负责数据库、加密、配置、鉴权这些脏活累活 依赖方向始终是外层指向内层： ```text interface_http -> application -> domain -> infrastructure ``` 下面这棵树直接对应当前项目实际目录： ```text com/trustbox ├── TrustBoxApplication.java # 系统总开关，Spring Boot 启动入口 ├── interface_http # 前台 / 接待处：负责接 HTTP 请求、回 JSON │ ├── controller # 前台服务员：接请求、调应用服务、返回结果 │ ├── dto │ │ ├── request # 客户填写的入参单据 │ │ └── response # 前台返给客户的回执单 │ ├── assembler # 翻译员：把 HTTP 单据翻成内部对象 │ └── advice # 前台统一话术：异常处理、统一错误响应 ├── application # 项目经理 / 业务办公室：负责编排业务用例，不保存业务规则 │ ├── accesscontrol # 权限控制用例：角色、菜单、导航、授权码流程 │ ├── audit # 审计用例：记录和查询关键操作日志 │ ├── auth # 登录认证用例：账号校验、JWT 签发、认证流程 │ ├── credential │ │ └── command # 凭证变更命令：偏写入动作的业务编排 │ ├── metadata # 主数据用例：分类、环境、类型、用户维护 │ ├── personal # 个人模式用例：本地库切换、个人数据库流程 │ └── secret │ ├── command # Secret 写操作用例：新增、编辑、删除、回滚、导入导出 │ └── query # Secret 读操作用例：列表、详情、导航、查询视图 ├── domain # 业务专家 / 大脑：业务规则真正落地的地方 │ └── secret # 当前最核心的领域边界，围绕 Secret 建模 │ ├── entity # 领域实体：有身份、有生命周期的核心对象 │ ├── valueobject # 值对象：表达不强调身份、强调语义和值的对象 │ ├── repository # 仓储接口：定义“要存什么、怎么取”，不关心具体数据库 │ └── service # 领域服务：跨实体规则，放不进单个实体时放这里 └── infrastructure # 后勤 / 工具人：不懂业务，但负责把技术细节做完 ├── config # 系统配置：Spring、MyBatis、Bean 装配 ├── crypto # 加解密工具：把密钥、算法、实现细节封起来 ├── datasource # 数据源适配：MySQL、SQLite、个人模式连接管理 ├── persistence │ ├── mybatis │ │ ├── dataobject # 数据库行对象：面向表结构，不等于领域对象 │ │ └── mapper # MyBatis Mapper：真正和 SQL / 表打交道 │ └── repositoryimpl # 仓储实现：把 domain 仓储接口落到 MyBatis 上 └── security # 安全技术实现：JWT、过滤器、当前用户、签名校验 ``` ### 各层职责说明 #### `interface_http` 这一层是“前台”，特点是只负责接待，不负责决策。 - 接收 HTTP 请求 - 做基础参数校验 - 调用 `application` 层 - 把结果包装成 JSON 响应 - 不直接写业务规则 - 不直接操作数据库 一句话理解： > 我只负责说人话，不负责懂业务。 #### `application` 这一层是“项目经理”，特点是负责流程编排，不负责定义规则本身。 - 表达一个个业务用例 - 协调多个领域对象或多个基础设施组件 - 控制执行顺序 - 区分读操作和写操作 - 不应该沉淀核心业务规则 一句话理解： > 我负责安排谁先干什么，但我不决定业务规则是什么。 #### `domain` 这一层是“业务专家”和“大脑”，是 DDD 最核心的部分。 - 承载业务规则 - 保证领域对象状态合法 - 不依赖 Spring、HTTP、数据库 - 关注“为什么这样做才对”，而不是“怎么存进去” 一句话理解： > 规则在这里安家，业务在这里长脑子。 #### `infrastructure` 这一层是“后勤”和“工具人”，负责所有外部世界的接入。 - 连接数据库 - 实现仓储接口 - 处理 JWT、过滤器、安全上下文 - 提供加密、数据源、配置等技术能力 - 可以替换实现，但不应该反过来定义业务规则 一句话理解： > 我不懂业务，但我能把事情落地。 ### 后端资源文件 位于 `backend/src/main/resources`： - `application.yml`：主配置文件 - `schema.sql`：MySQL 初始化脚本 - `schema-sqlite.sql`：SQLite 初始化脚本 - `docs/integration-readme.md`：集成接口说明文档 ### 测试结构 - `backend/src/test/java`：测试代码 - `backend/src/test/resources/application-test.yml`：测试环境配置 - `backend/target/surefire-reports`：测试执行报告 ## 前端模块结构 前端代码位于 `frontend/src`。 - `api`：按业务域拆分的接口访问层，包括认证、权限、审计、主数据、Secret、个人库等 - `components`：复用组件和业务对话框，如 Secret 详情、编辑、查看明文、角色菜单弹窗等 - `router`：前端路由定义 - `stores`：Pinia 状态管理，当前可见 `session` 与 `secrets` - `types`：TypeScript 类型定义 - `utils`：工具函数，例如自动填充逻辑辅助 - `views`：页面级视图，包括概览、Secrets、用户、角色、菜单、审计、系统设置等 - `App.vue` / `main.ts`：应用入口 - `style.css`：全局样式 ## 插件模块结构 插件位于 `plugin/trustbox-autofill`。 - `manifest.json`：插件声明 - `background.js`：后台任务与消息分发 - `content.js`：页面 DOM 识别与自动填充逻辑 - `popup.html` / `popup.js`：插件弹窗界面 - `trustbox-autofill.crx`：已打包扩展文件 - `trustbox-autofill.pem`：插件签名私钥文件 ## OpenSpec 结构 `openspec` 目录用于管理需求和变更过程： - `openspec/AGENTS.md`：协作说明 - `openspec/project.md`：项目级说明 - `openspec/specs`：稳定规格 - `openspec/changes/*`：各项功能变更提案、设计和任务清单 当前已能看到的变更主题包括： - 审计中心 - 浏览器插件自动填充 - 环境与类型元数据 CRUD - 集成 Key 权限控制 - 密码登录 - 角色菜单管理 - Secret 核心能力 - Secret Excel 导入导出 - Secret 二次校验查看 - Secret URL 导航 - Secret 版本查看 - JWT 认证模型调整 ## 目录结构 ```text TrustBox/ ├── backend/ │ ├── src/main/java/com/trustbox/ │ │ ├── application/ │ │ ├── domain/ │ │ ├── infrastructure/ │ │ ├── interface_http/ │ │ └── TrustBoxApplication.java │ ├── src/main/resources/ │ ├── src/test/ │ ├── pom.xml │ └── mvnw ├── frontend/ │ ├── src/ │ │ ├── api/ │ │ ├── components/ │ │ ├── router/ │ │ ├── stores/ │ │ ├── types/ │ │ ├── utils/ │ │ └── views/ │ └── package.json ├── plugin/ │ └── trustbox-autofill/ ├── openspec/ └── README.md ``` ## 运行环境要求 ### 后端 - JDK 25 - MySQL 8.x - Maven 3.9+，或直接使用仓库内 `./mvnw` ### 前端 - Node.js 20+ - npm ### Native Image - GraalVM JDK - `native-image` 组件 ## 本地启动 ### 1. 准备数据库 建议使用 MySQL 8，先创建数据库： ```sql CREATE DATABASE trustbox DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` ### 2. 配置后端 主配置文件： - `backend/src/main/resources/application.yml` 重点确认： - `spring.datasource.url` - `spring.datasource.username` - `spring.datasource.password` - `trustbox.auth.jwt-secret` - `trustbox.crypto.master-key` - `trustbox.mfa.*` - `trustbox.integration.*` - `trustbox.personal-mode.db-directory` 项目启动后会结合初始化脚本和迁移逻辑完成表结构准备。 ### 3. 启动后端 ```bash cd backend ./mvnw spring-boot:run ``` 默认后端地址： ```text http://localhost:8080/api/v1 ``` ### 4. 启动前端 ```bash cd frontend npm install npm run dev ``` 默认前端地址： ```text http://localhost:5173 ``` ## 构建命令 ### 后端 JVM 包 ```bash cd backend ./mvnw clean package ``` ### 后端 GraalVM 原生二进制 ```bash cd backend export JAVA_HOME=/path/to/graalvm-jdk-25 export PATH="$JAVA_HOME/bin:$PATH" ./mvnw -Pnative -DskipTests native:compile ``` 原生可执行文件默认输出到： ```text backend/target/trustbox-backend ``` 运行方式： ```bash ./target/trustbox-backend ``` 说明： - `native` profile 只影响 GraalVM 构建，不影响默认 JVM 打包流程 - 本项目使用 Spring Boot 3、MyBatis-Plus、MySQL、SQLite 和第三方 Excel 组件，Native Image 需要重点回归数据库、Mapper 扫描、个人模式和导入导出链路 - 如 GraalVM for JDK 25 兼容性不稳定，可评估先回落到 JDK 21 LTS 再做 Native Image 交付 ### 前端构建 ```bash cd frontend npm run build ``` ## 默认约束 - 前端默认请求地址为 `http://localhost:8080/api/v1` - 系统内置超级管理员账号为 `admin` - `admin` 不允许删除，也不允许修改账户名 ## 排查与调试 ### 日志 当前项目关键链路已补充日志，主要覆盖： - 登录认证 - Secret 增删改查 - 明文查看与版本回滚 - 主数据维护 - 集成 Key 创建、状态切换、签名校验、权限拒绝 - 审计日志写入 - 启动时数据库兼容处理 - 前端请求链路和 Secret Store 状态变化 注意： - 日志不应输出 Secret 明文、TOTP 验证码、Secret Key 明文 - 前端浏览器控制台日志适合联调，不建议视为正式审计记录 ### 测试报告 如果 Maven 测试失败，可查看： - `backend/target/surefire-reports`：每个测试用例的详细报告 - `*.dump` / `*.dumpstream`：测试 JVM 异常退出或崩溃时的附加诊断文件 ## 后续建议 - 增加 `docker-compose.yml` 统一本地依赖 - 补充更完整的单元测试和集成测试 - 增加 `LICENSE`、`CONTRIBUTING.md`、`SECURITY.md` - 补充部署文档、初始化账号策略和生产环境配置示例