# 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
* 私钥和命令执行放在服务端受控环境
* 每台设备独立证书，便于吊销和追踪