# Security Key

**Repository Path**: SkyTing/security-key

## Basic Information

- **Project Name**: Security Key
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Security-Key

<div align="center">

**企业内部密码管理系统**

多角色权限 · 部门/小组组织 · 密码组与条目 · 操作审计 · 邀请与初始化向导

---

## 目录

- [项目简介](#项目简介)
- [程序架构](#程序架构)
  - [总体分层](#总体分层)
  - [后端模块（Go + Gin）](#后端模块go--gin)
  - [前端模块（Vue 3）](#前端模块vue-3)
  - [请求与安全链路](#请求与安全链路)
  - [构建与部署形态](#构建与部署形态)
- [仓库结构](#仓库结构)
- [核心能力](#核心能力)
- [开源协议](#开源协议)
- [快速启动](#快速启动)

---

## 项目简介

Security-Key 面向企业内部场景，在**组织维度**（部门、小组）与**权限维度**（角色、密码组授权）上管理敏感条目，并提供**操作日志**与**邀请流程**（含公开链接接受邀请）。  
后端为 **Go + Gin + GORM + MySQL**；前端为 **Vue 3 + TypeScript + Vite + Naive UI**。

---

## 程序架构

### 总体分层

```text
┌─────────────────────────────────────────────────────────────┐
│                     浏览器 / 客户端                           │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTP / JSON
┌───────────────────────────▼─────────────────────────────────┐
│  前端 SPA（Vue Router + Pinia + Axios）                      │
│  开发态：Vite Dev Server；生产态：静态资源由后端托管           │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Go + Gin 应用层                                             │
│  Handler → Service → GORM / MySQL                            │
│  Middleware（JWT / 鉴权 / 操作日志 / 异常）· 初始化/动态数据源 │
└─────────────────────────────────────────────────────────────┘
```

### 后端模块（Go + Gin）

| 层次 | 职责 | 典型包路径 |
|------|------|------------|
| **Handler** | REST 接口、参数绑定校验、返回统一响应 | `internal/handler` |
| **Service** | 业务编排、事务边界、领域规则 | `internal/service` |
| **Model** | GORM 实体与表结构映射 | `internal/model` |
| **DTO** | 入参/出参结构与 API 契约 | `internal/dto` |
| **Security** | JWT 签发与校验、当前用户上下文 | `internal/security` |
| **Crypto** | AES-GCM 加解密、密码强度策略 | `internal/crypto` |
| **Middleware** | JWT 解析、鉴权/角色、操作日志、CORS、异常恢复 | `internal/middleware` |
| **Datasource** | 可热切换的 GORM 数据源（动态数据源） | `internal/datasource` |
| **Config / Router** | 环境变量配置、路由装配与静态资源托管 | `internal/config`、`internal/router` |

**与业务强相关的横切能力：**

- **初始化向导（Setup）**：首次部署时引导配置数据库等；`SetupStatus` 中间件在未完成初始化时拦截 `/api/**`（除 `/api/setup`）返回 `403 系统尚未初始化`。
- **动态数据源**：`internal/datasource` 维护可在运行期热切换的 GORM 句柄；向导校验连接成功后 `AutoMigrate` 建表并切换（切换仅存内存，重启回到环境变量配置的初始数据源）。
- **密码条目保护**：账号/密码字段以 AES-GCM 加密存储（兼容旧 ECB 密文），明文仅在校验权限后解密返回；权限在 Service 层与授权表（密码组/条目访问关系）中落实。
- **公开邀请**：`/api/invitations/accept-by-token` 提供免登录场景下的安全边界（JWT `invite_accept` 令牌校验），与站内邀请流程区分。

### 前端模块（Vue 3）

| 区域 | 说明 |
|------|------|
| **路由** | `vue-router` 组织页面与鉴权相关导航 |
| **状态** | `pinia` 管理登录态、用户信息等 |
| **UI** | `naive-ui` 组件库 |
| **HTTP** | `axios` 封装 API，与后端 JWT 约定配合 |
| **构建** | `vite` 开发与打包；`build:static` 可将产物同步到后端静态目录（见下节） |

### 请求与安全链路

```text
请求进入
  → ParseToken 中间件（解析 Bearer access 令牌、注入当前用户）
  → RequireAuth / RequireRoles 中间件（鉴权与角色控制）
  → Handler（参数绑定校验）
  → Service（业务规则 + 事务）
  → GORM / MySQL
  → 返回 JSON

写操作经 OpLog 中间件 → 记录操作日志（含操作人、IP 等）
异常经 fail 助手与 Recovery 中间件转换为规范 HTTP 状态与统一响应体
```

### 构建与部署形态

1. **前后端分离开发**：前端 `npm run dev`，后端 `go run ./cmd/server` 运行，通过代理或跨域访问 API。  
2. **一体化部署**：前端执行 `npm run build:static`（`package.json` 中 `build:static`），将构建结果输出到 `backend/static`；后端二进制同时提供 **API** 与 **SPA 静态文件**；路由层的 SPA 回退（`NoRoute`）负责前端路由刷新时回退到 `index.html`。

---

## 仓库结构

| 路径 | 说明 |
|------|------|
| `backend/` | Go + Gin 工程：`cmd/server` 入口、`internal/*` 各层、`static/` 托管前端产物 |
| `frontend/` | Vue 3 + Vite 工程 |

---

## 核心能力

- 用户、部门、小组管理  
- 密码组与密码条目（含可见性/授权、AES 加密与密码变更历史）  
- 站内邀请与邮件邀请（公开链接接受邀请等场景由专门接口承载）  
- 操作日志审计  
- 初始化向导与动态数据源（向导参数加密持久化，重启自动恢复）  
- 安全：会话吊销（登出/改密/改角色即时失效）、登录限速与锁定、MFA(TOTP)、强制改密、密钥版本化与轮换  
- 工程化：健康探针 `/healthz` `/readyz`、指标 `/metrics`、API 文档 `/v3/api-docs` 与 `/swagger-ui.html`、优雅关闭、结构化日志、Docker/CI  

> 部署与运维（环境变量、容器化、迁移、密钥轮换、安全基线）详见 [`backend/DEPLOY.md`](backend/DEPLOY.md)。

---

## 开源协议

本项目采用 **GNU Affero General Public License v3.0（AGPL-3.0）** 发布，详见 [`LICENSE`](LICENSE)。

你可以自由使用、复制、修改和分发本项目，包括商业使用；如果你修改本项目并通过网络服务形式向用户提供访问，需要按照 AGPL-3.0 的要求向这些用户提供对应源码。

---

## 快速启动

### 方式一：Docker 快速体验（推荐）

只需要本机安装 Docker：

```bash
docker compose up -d
```

访问：`http://localhost:8080`

首次进入初始化向导时，数据库填写：

| 字段 | 值 |
|------|----|
| 类型 | `MYSQL` |
| Host | `mysql` |
| Port | `3306` |
| 数据库名 | `security_key` |
| 用户名 | `root` |
| 密码 | `root` |

为避免和本机已有 MySQL 冲突，默认编排把 MySQL 暴露到宿主机 `13306`；容器内部仍是 `mysql:3306`，所以初始化向导仍按上表填写。

根目录 `docker-compose.yml` 默认使用已发布到 Docker Hub 的多架构应用镜像 `mcskyding/security-key:latest`。Compose 项目名固定为 `security-key`，容器会带项目前缀，例如 `security-key-app-1`、`security-key-mysql-1`。

Docker 镜像默认发布 `linux/amd64` 与 `linux/arm64`，覆盖主流 Windows / macOS / Linux 的 Docker 使用场景：

| 使用环境 | Docker 平台 |
|----------|-------------|
| Windows x86_64 Docker Desktop | `linux/amd64` |
| Intel Mac Docker Desktop | `linux/amd64` |
| Apple Silicon Mac Docker Desktop | `linux/arm64` |
| Linux x86_64 服务器/桌面 | `linux/amd64` |
| Linux ARM64 服务器/开发板 | `linux/arm64` |

### 方式二：本地开发

#### 后端

在 `backend` 目录：

```bash
go build -o security-key ./cmd/server
./security-key
# 或直接运行：go run ./cmd/server
```

默认服务地址：`http://localhost:8080`

主要环境变量（均有默认值，括号内为默认）：`SK_PORT`(8080)、`SK_DB_HOST`(localhost)、`SK_DB_PORT`(3306)、`SK_DB_NAME`(security_key)、`SK_DB_USERNAME`(root)、`SK_DB_PASSWORD`(root)、`SK_JWT_SECRET`、`SK_AES_KEY`(32 字节)、`SK_SETUP_ENABLED`(true)、`SK_FRONTEND_BASE_URL`、`SK_CORS_ALLOWED_ORIGINS`。

**首次部署请通过系统提供的初始化向导完成数据库与管理配置，不要使用文档中的任何示例账号密码。**

#### 前端

在 `frontend` 目录：

```bash
npm install
npm run dev
```

默认开发地址：`http://localhost:3000`

#### 生产静态资源并入后端

```bash
cd frontend
npm run build:static
```

再按后端方式打包/启动 Go 服务，即可由同一端口提供页面与接口。

---

<div align="center">
**Security-Key** — 内部密码与权限治理