# 🛡️ MinSec
**轻量级、零知识端到端加密（E2EE）环境变量与 Secret 管理工具**
*内存零落地注入 • 抵御 AI IDE/大模型机密泄露 • Cloudflare D1 与 SQLite 双模式运行*
[](LICENSE)
[](https://nodejs.org/)
[](https://workers.cloudflare.com/)
[English](https://www.npmjs.com/package/minsec) | [简体中文](https://cdn.jsdelivr.net/npm/minsec/README_CN.md) | [日本語](https://cdn.jsdelivr.net/npm/minsec/README_JA.md)
---
## 📖 目录
- [为什么需要 MinSec？（核心痛点与目的）](#-为什么需要-minsec核心痛点与目的)
- [1. 消除 AI 编程工具与大模型的隐私泄露盲区](#1-消除-ai-编程工具与大模型的隐私泄露盲区)
- [2. 团队无痛协作与权限即时作废](#2-团队无痛协作与权限即时作废)
- [3. 企业内网自托管与数据主权](#3-企业内网自托管与数据主权)
- [全局安装 CLI（npm / pnpm / yarn）](#-全局安装-clinpm--pnpm--yarn)
- [技术架构与信封加密原理](#-技术架构与信封加密原理)
- [两种部署运行模式](#-两种部署运行模式)
- [模式 A：本地 / 公司内网部署（轻量 SQLite）](#模式-a本地--公司内网部署轻量-sqlite)
- [模式 B：Serverless 边缘无服务化部署（Cloudflare Workers + D1）](#模式-bserverless-边缘无服务化部署cloudflare-workers--d1)
- [常用 CLI 命令行速查](#-常用-cli-命令行速查)
- [Web 管理端核心特性](#-web-管理端核心特性)
- [⚠️ 极度重要备份提醒：Root Key（根密钥）](#️-极度重要备份提醒root-key根密钥)
- [项目配置文件规范（.minsec）](#-项目配置文件规范minsec)
- [开源协议与商业授权说明](#-开源协议与商业授权说明)
---
## 💡 为什么需要 MinSec？（核心痛点与目的）
### 1. 消除 AI 编程工具与大模型的隐私泄露盲区
在当前 AI 辅助编程时代，诸如 **Claude Code、Cursor、GitHub Copilot、Codex、Gemini Code Assist** 等 AI IDE 与智能 Agent 会高频地对整个工作区进行上下文扫描与文件解析。
* **传统痛点**：传统项目通常直接把生产数据库密码、第三方支付密钥、AWS Token 等明文硬编码在本地 `.env` 文件中。开发者在使用 AI 工具时，极易无意识地将包含私密信息的 `.env` 整体打包上传至外部 LLM 云端服务器与训练日志中。
* **MinSec 解决方案**：**「内存零落地注入」（Zero-Disk In-Memory Injection）**。
```bash
minsec run -- npm run dev
```
在子进程启动的瞬间，MinSec 通过加密流动态拉取并解密配置，**直接注入到子进程的 RAM 内存中（`process.env`）**。**磁盘上永远不会产生任何明文敏感文件**，工作区内只有一份完全公开安全的 `.minsec` 链接引导文件。
### 2. 团队无痛协作与权限即时作废
* **告别散落传递**：再也不用把 `.env` 文件打包通过 Slack、微信、钉钉或邮件四处转发。
* **成员离职即时作废**：当外包人员或员工离职时，管理员只需在 Web 端点击一次即可作废其 API Key，该成员电脑上的命令行将瞬间失去所有解密权限。
* **服务端统一修改，全员实时同步**：数据库密码或核心密钥轮换时，管理员只需在 MinSec 控制台修改一次，全团队所有人与 CI/CD 机器在下一次运行 `minsec run` 时立即加载新值，无需每个人都手动改本地 `.env`。
### 3. 企业内网自托管与数据主权
MinSec 原生支持纯内网离线运行，也可一键部署至 Cloudflare 边缘计算，企业对私有密钥拥有 100% 的绝对物理控制权。
---
## 📦 全局安装 CLI（npm / pnpm / yarn）
通过您偏好的包管理器全局安装 `minsec`，即可在系统的任何终端与目录下直接运行 `minsec` 命令：
```bash
# 使用 npm 全局安装
npm install -g minsec
# 使用 pnpm 全局安装
pnpm add -g minsec
# 使用 yarn 全局安装
yarn global add minsec
```
安装完成后，可在任何地方直接执行：
```bash
# 查看版本与命令列表
minsec --help
# 启动本地守护服务与 Web 控制台
minsec server
```
---
## 🔒 技术架构与信封加密原理
MinSec 遵循严苛的**零知识信封加密体系（Envelope Encryption）**：
```
┌──────────────────────────────────────────────┐
│ Master Root Key（最高权限根密钥 256 位） │
│ (存在 ~/.minsec/server.key 或 Cloudflare Secret)│
└──────────────────────┬───────────────────────┘
│ 加密 / 解密
▼
┌──────────────────────┐ ┌──────────────────────────────────────────────┐
│ 环境变量 / 密文明文 │ ───► │ Project Key（每个项目独立的 256 位项目密钥）│
└──────────────────────┘ └──────────────────────┬───────────────────────┘
│ AES-256-GCM 密文加密
▼
┌──────────────────────────────────────────────┐
│ 存入 Cloudflare D1 / 本地 SQLite 数据库的密文 │
└──────────────────────────────────────────────┘
```
1. **Root Key（根密钥）**：系统最高权限密钥，仅驻留在服务端物理环境中。
2. **Project Key（项目密钥）**：每个项目生成完全独立的高强度 AES-256 密钥，受 Root Key 保护。
3. **数据库全密文存储**：数据库中的所有 Secret 均以加盐的 AES-256-GCM 密文字符串形态存储，服务端与数据库脱机也不会泄露任何明文。
---
## 🚀 两种部署运行模式
### 模式 A：本地 / 公司内网部署（轻量 SQLite）
MinSec 内置了基于 Hono 与 SQLite 的轻量级服务，无需安装繁重的 Docker 即可单机极速启动：
```bash
# 方式 1：若已全局安装
minsec server --port 9876
# 方式 2：从源码克隆运行
npm install
node bin/minsec-server
```
启动后，在浏览器访问 **`http://localhost:9876/`** 即可根据指引创建超级管理员账号。
### 模式 B：Serverless 边缘无服务化部署（Cloudflare Workers + D1）
一条命令即可将 MinSec 全套服务部署至全球分布的 Cloudflare 边缘网络：
```bash
minsec deploy cloudflare
```
部署脚本全自动完成：
1. 检测本机 Cloudflare `wrangler` 登录状态；
2. 自动在云端创建 Cloudflare D1 分布式数据库（`minsec-db`）；
3. 自动向远程 D1 导入数据表结构脚本；
4. 自动生成并在云端注入 `MINSEC_ROOT_KEY` 与 `JWT_SECRET` 加密凭证；
5. 部署 Cloudflare Worker（同时内置 REST API 与完整的 Web 单页管理端），并输出访问地址：
```
🌐 MinSec Endpoint: https://minsec-api..workers.dev
```
---
## 💻 常用 CLI 命令行速查
### 配置全局服务器凭据
```bash
# 将本地 CLI 全局绑定到线上或内网服务
minsec config set --global --endpoint https://minsec-api.your-domain.workers.dev --key ms_tok_...
# 查看当前生效的配置状态
minsec config
```
### 初始化项目绑定（创建 .minsec）
在您的项目根目录下执行：
```bash
minsec init
```
* 交互式询问并生成项目 `.minsec` 链接文件；
* 自动扫描 Monorepo 多包目录（如 `apps/*`、`packages/*`），自动在各子项目中创建关联配置。
### 内存直接注入运行（核心功能，磁盘零文件）
`minsec run` 在操作系统内核层（OS Process）为子进程注入环境变量。因此，**它原生支持任何编程语言与运行时（Node.js、Go、Rust、Java、Python、Docker 等），原理完全通用且无需额外配置**。
```bash
# Node.js
minsec run -- npm run dev
minsec run --env prod --path /apps/web -- npm start
# Go（开发运行或执行编译后的二进制）
minsec run -- go run main.go
minsec run -- ./bin/server
# Rust（Cargo 运行或执行 Release 二进制）
minsec run -- cargo run
minsec run -- ./target/release/my-app
# Java（Spring Boot、Gradle 或原生 Jar）
minsec run -- ./mvnw spring-boot:run
minsec run -- ./gradlew bootRun
minsec run -- java -jar target/app.jar
# Python / Shell / 任何命令行
minsec run -- python main.py
minsec run -- docker compose up
```
#### 各语言代码内读取方式
| 语言 | 代码读取示例 | 特别说明 |
| :--- | :--- | :--- |
| **Node.js** | `process.env.DATABASE_URL` | 原生标准库读取 |
| **Go** | `os.Getenv("DATABASE_URL")` | 原生标准库读取 |
| **Rust** | `std::env::var("DATABASE_URL")` | 原生标准库读取 |
| **Java** | `System.getenv("DATABASE_URL")` | ⚠️ **特别说明**：MinSec 注入的是操作系统的**环境变量**（OS Environment Variables），因此在 Java 代码中**必须使用 `System.getenv(...)` 读取**，而**不能使用** `System.getProperty(...)`（后者仅用于 Java `-D` JVM 参数）。主流现代框架（如 Spring Boot、Quarkus、Micronaut）均具备宽松绑定能力，会自动将环境变量映射到 `application.yml` 或 `@Value("${database.url}")` 中。 |
| **Python** | `os.getenv("DATABASE_URL")` | 原生标准库读取 |
### CLI 读写变量与 Secret
```bash
# 设置普通环境变量
minsec set PORT=3000
# 设置端到端加密的 Secret
minsec set STRIPE_KEY=sk_live_1234567890 --secret
# 列出当前项目当前环境下的所有配置项
minsec list
```
### 导出与导入加密备份包
```bash
# 导出指定项目（支持多选导出，加密生成 .minsec.vault 文件）
minsec export --projects my-project,auth-service --output backup.minsec.vault
# 导入备份包（自动检测重名冲突并重命名）
minsec import backup.minsec.vault
```
### 本地管理员密码重置（应急恢复）
```bash
minsec reset-password --username admin
```
---
## 🖥️ Web 管理端核心特性
本地服务与 Cloudflare Worker 的根路径（`/`）均内置了全功能单页控制台（SPA）：
* **多项目管理**：支持多个业务项目，左侧侧边栏极速切换。
* **Monorepo 层级 Path 支持**：支持在项目内按路径组织服务（如 `/`、`/apps/web`、`/apps/api`），子路径智能继承根路径变量。
* **多环境管理**：内置 `dev`、`staging`、`prod` 环境，并支持随时点击 `+` 新增自定义环境。
* **环境变量一键同步（🔄 同步变量）**：支持从源环境一键复制变量名（值留空供各环境自行配置）或连同值一并同步。
* **项目级 API Key 授权管控**：支持生成限制特定项目权限、指定过期时间（7天/30天/90天/永久）的团队访问 Token。
* **多项目按需打包导出/导入**：导入导出支持复选指定项目，并由共享密码全程加密。
* **安全防误删机制**：项目内只要存在配置项即严禁删除，只有空项目才允许安全删除。
* **一键复制 Project ID 与配置模板**：
- `ID: 📋`：点击直接复制真实项目 ID；
- `📋 Copy .minsec`：一键生成即用型 `.minsec` JSON 配置块，直接粘贴至项目。
---
## ⚠️ 极度重要备份提醒：Root Key（根密钥）
> [!CAUTION]
> **部署完成后，请务必第一时间离线备份您的 Root Key！**
> MinSec 严格遵循零知识加密原则，服务端一旦失去 Root Key，**数据库中所有加密的 Secret 数据将永久损毁且在数学上绝对无法被恢复！**
1. **本地 / 内网部署**：
* 请立即备份文件：`~/.minsec/server.key`
* 请将其妥善保存在安全的物理介质或团队离线密码库（如 1Password、KeePass）中。
2. **Cloudflare 部署**：
* 请备份部署日志中生成的 `MINSEC_ROOT_KEY`；
* 您也可以在 Cloudflare 控制台查看与更新该密钥：
`Workers & Pages` ➔ `minsec-api` ➔ `Settings` ➔ `Variables and Secrets` ➔ `MINSEC_ROOT_KEY`。
---
## 📋 项目配置文件规范（.minsec）
项目中生成的 `.minsec` 文件结构如下：
```json
{
"endpoint": "",
"apiKey": "",
"projectId": "myproject",
"projectName": "myproject",
"defaultEnv": "dev",
"defaultPath": "/"
}
```
* **继承规则**：当 `endpoint` 或 `apiKey` 为留空字符串（`""`）时，CLI 会自动向全局配置（`~/.minsec/.minsec`）回退继承，多项目开发无需重复配置服务器地址与 Token。
* **容错性**：`projectId` 既可以填写机器生成的 ID（如 `prj_59df...`），也可以直接填写项目名称（如 `myproject`），服务端底层已做全自动双向识别。
---
## 📄 开源协议与商业授权说明
本项目使用 **MinSec 非商业开源许可协议（Version 1.0）**：
* **非商业免费**：允许个人项目、内部学习、学术研究、非营利性机构免费使用、修改及自托管。
* **禁止商业使用**：任何商业公司、营利性机构在商业环境中的部署运行、集成到商业产品中，或作为商业化 SaaS/托管服务对外提供，**均必须获得原作者的书面商业授权与许可**。
如需获取商业授权或技术支持，请联系项目作者。