step-web/任务.md

Step Admin 项目骨架说明

项目目标

这是一个基于 SvelteKit + SQLite + step CLI 的轻量证书管理后台，用于管理 step-ca 签发的客户端证书。

适用场景：

• 管理员登录后台
• 创建设备证书
• 下载 crt / key / p12
• 吊销证书
• 记录证书元数据与审计日志

技术栈

• 前后端一体：SvelteKit
• 数据库：SQLite
• 命令执行：step CLI
• 运行方式：Node adapter + systemd + Caddy 反代

项目结构

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 密码

环境变量建议

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