288 lines
5.2 KiB
Markdown
288 lines
5.2 KiB
Markdown
# Step Admin 项目骨架说明
|
||
|
||
## 项目目标
|
||
|
||
这是一个基于 **SvelteKit + SQLite + step CLI** 的轻量证书管理后台，用于管理 `step-ca` 签发的客户端证书。
|
||
|
||
适用场景：
|
||
|
||
* 管理员登录后台
|
||
* 创建设备证书
|
||
* 下载 `crt / key / p12`
|
||
* 吊销证书
|
||
* 记录证书元数据与审计日志
|
||
|
||
## 技术栈
|
||
|
||
* 前后端一体：SvelteKit
|
||
* 数据库：SQLite
|
||
* 命令执行：`step` CLI
|
||
* 运行方式：Node adapter + systemd + Caddy 反代
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
step-admin/
|
||
├─ package.json
|
||
├─ svelte.config.js
|
||
├─ vite.config.ts
|
||
├─ tsconfig.json
|
||
├─ .env.example
|
||
├─ src/
|
||
│ ├─ app.d.ts
|
||
│ ├─ app.html
|
||
│ ├─ hooks.server.ts
|
||
│ ├─ lib/
|
||
│ │ ├─ server/
|
||
│ │ │ ├─ auth.ts
|
||
│ │ │ ├─ db.ts
|
||
│ │ │ ├─ schema.ts
|
||
│ │ │ ├─ step.ts
|
||
│ │ │ ├─ files.ts
|
||
│ │ │ └─ audit.ts
|
||
│ │ └─ types.ts
|
||
│ └─ routes/
|
||
│ ├─ +layout.server.ts
|
||
│ ├─ +layout.svelte
|
||
│ ├─ login/
|
||
│ │ ├─ +page.svelte
|
||
│ │ └─ +server.ts
|
||
│ ├─ logout/
|
||
│ │ └─ +server.ts
|
||
│ ├─ dashboard/
|
||
│ │ └─ +page.svelte
|
||
│ ├─ certificates/
|
||
│ │ ├─ +page.server.ts
|
||
│ │ ├─ +page.svelte
|
||
│ │ └─ create/
|
||
│ │ ├─ +page.svelte
|
||
│ │ └─ +server.ts
|
||
│ └─ api/
|
||
│ └─ certificates/
|
||
│ ├─ [id]/
|
||
│ │ ├─ download/
|
||
│ │ │ └─ +server.ts
|
||
│ │ └─ revoke/
|
||
│ │ └─ +server.ts
|
||
├─ scripts/
|
||
│ └─ init-db.ts
|
||
└─ data/
|
||
├─ app.db
|
||
└─ certs/
|
||
```
|
||
|
||
## 核心模块说明
|
||
|
||
### 1. 认证模块
|
||
|
||
文件：`src/lib/server/auth.ts`
|
||
|
||
作用：
|
||
|
||
* 管理员账号密码校验
|
||
* Session Cookie 签发与校验
|
||
* 登录态注入到 `event.locals`
|
||
|
||
建议：
|
||
|
||
* 初期可用单管理员密码登录
|
||
* 后期可接入 OIDC / 企业 SSO
|
||
|
||
### 2. 数据库模块
|
||
|
||
文件：
|
||
|
||
* `src/lib/server/db.ts`
|
||
* `src/lib/server/schema.ts`
|
||
* `scripts/init-db.ts`
|
||
|
||
主要存储：
|
||
|
||
* 证书 subject
|
||
* 设备名称
|
||
* 序列号
|
||
* 创建时间
|
||
* 过期时间
|
||
* 吊销时间
|
||
* 文件路径
|
||
* 创建者
|
||
|
||
### 3. step 命令封装模块
|
||
|
||
文件：`src/lib/server/step.ts`
|
||
|
||
建议封装的方法：
|
||
|
||
* `createCertificate()`
|
||
* `createP12()`
|
||
* `revokeCertificate()`
|
||
* `inspectCertificate()`
|
||
|
||
实现方式：
|
||
|
||
* 使用 Node.js 的 `child_process.execFile`
|
||
* 服务端调用 `step` 命令
|
||
* 严禁在前端执行任何证书命令
|
||
|
||
### 4. 文件管理模块
|
||
|
||
文件：`src/lib/server/files.ts`
|
||
|
||
作用：
|
||
|
||
* 统一管理 `crt / key / p12` 文件路径
|
||
* 控制下载输出
|
||
* 避免把证书目录直接暴露成静态目录
|
||
|
||
### 5. 审计日志模块
|
||
|
||
文件：`src/lib/server/audit.ts`
|
||
|
||
记录行为：
|
||
|
||
* 登录
|
||
* 创建设备证书
|
||
* 下载证书
|
||
* 吊销证书
|
||
|
||
## 页面设计
|
||
|
||
### 登录页
|
||
|
||
* 用户名
|
||
* 密码
|
||
* 登录按钮
|
||
|
||
### 仪表盘
|
||
|
||
* 证书总数
|
||
* 已吊销数量
|
||
* 即将过期证书数量
|
||
|
||
### 证书列表页
|
||
|
||
字段：
|
||
|
||
* 设备名
|
||
* Subject
|
||
* 序列号
|
||
* 状态
|
||
* 创建时间
|
||
* 过期时间
|
||
* 操作按钮
|
||
|
||
操作：
|
||
|
||
* 下载
|
||
* 查看详情
|
||
* 吊销
|
||
|
||
### 创建设备证书页
|
||
|
||
表单建议：
|
||
|
||
* 设备名称
|
||
* Subject
|
||
* 证书有效期（小时 / 天）
|
||
* 是否导出 p12
|
||
* p12 密码
|
||
|
||
## 环境变量建议
|
||
|
||
```env
|
||
APP_ADMIN_USERNAME=admin
|
||
APP_ADMIN_PASSWORD_HASH=
|
||
APP_SESSION_SECRET=change-me
|
||
|
||
STEP_BIN=/usr/bin/step
|
||
STEP_CONTEXT=internal-ca
|
||
STEP_ROOT_CA=/var/lib/step-ca/certs/root_ca.crt
|
||
STEP_OUTPUT_DIR=./data/certs
|
||
|
||
DEFAULT_CERT_HOURS=8760
|
||
```
|
||
|
||
## 证书签发流程
|
||
|
||
### 管理后台创建证书
|
||
|
||
1. 管理员登录后台
|
||
2. 提交设备名与 subject
|
||
3. 服务端调用 `step ca certificate`
|
||
4. 生成 `crt / key`
|
||
5. 可选调用 `step certificate p12`
|
||
6. 将元数据写入 SQLite
|
||
7. 返回下载链接
|
||
|
||
### 吊销流程
|
||
|
||
1. 管理员在列表页点击吊销
|
||
2. 服务端根据序列号执行 `step ca revoke`
|
||
3. 更新数据库状态为 `revoked`
|
||
4. 写入审计日志
|
||
|
||
## 安全建议
|
||
|
||
### 必须做到
|
||
|
||
* Web 服务不要以 root 运行
|
||
* `step` 命令只允许在服务端执行
|
||
* 私钥文件权限严格控制
|
||
* 下载接口必须鉴权
|
||
* 证书目录不要公开暴露
|
||
|
||
### 建议做到
|
||
|
||
* 每台设备单独一张证书
|
||
* 文件下载带审计日志
|
||
* 吊销前二次确认
|
||
* 定期备份 SQLite 与元数据
|
||
|
||
## 推荐部署方式
|
||
|
||
### 应用层
|
||
|
||
* SvelteKit 使用 `adapter-node`
|
||
* systemd 管理 Node 进程
|
||
* Caddy 反代应用
|
||
|
||
### 数据层
|
||
|
||
* SQLite 起步
|
||
* 后期可迁移 PostgreSQL
|
||
|
||
### step 命令层
|
||
|
||
* 后端调用系统中的 `step`
|
||
* `step-ca` 独立运行，不与 Web 服务同权限
|
||
|
||
## 第一版最小可用功能
|
||
|
||
建议优先做：
|
||
|
||
1. 登录
|
||
2. 证书列表
|
||
3. 创建设备证书
|
||
4. 下载 `crt / key / p12`
|
||
5. 吊销证书
|
||
|
||
## 第二版扩展功能
|
||
|
||
* 证书到期提醒
|
||
* 搜索与筛选
|
||
* 批量导出
|
||
* 多管理员角色
|
||
* OIDC 登录
|
||
* 用户自助申请与审批
|
||
|
||
## 总结
|
||
|
||
这是一个适合内部使用的轻量 step-ca 管理后台骨架。
|
||
|
||
重点原则：
|
||
|
||
* Web 后台只做管理和审计
|
||
* `step-ca` 继续做真正的 CA
|
||
* 私钥和命令执行放在服务端受控环境
|
||
* 每台设备独立证书，便于吊销和追踪
|