139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# Step Admin
|
||
|
||
这是一个基于 SvelteKit + SQLite + `step` CLI 构建的轻量级证书管理后台系统。旨在用于方便管理由 `step-ca` 签发的内网设备客户端证书。
|
||
|
||
## 主要特性
|
||
|
||
- 🛡️ 安全的 Admin 登录保护
|
||
- 📊 仪表盘展示证书状态统计
|
||
- 📄 发行、吊销设备证书并记录状态
|
||
- 📦 一键下载 `.crt` 证书及直接导出 `.p12` 格式
|
||
- 📝 记录基于 SQLite 的基础审计日志
|
||
|
||
---
|
||
|
||
## 🛠 开发环境搭建
|
||
|
||
### 1. 环境依赖
|
||
1. Node.js >= 20
|
||
2. [`step` CLI](https://smallstep.com/docs/step-cli/installation) 命令行工具（确保在环境变量 `PATH` 中可用）。
|
||
3. 你的本地或远程的 `step-ca` 根 CA 已被系统信任（用于正常测试颁发与吊销）。
|
||
|
||
### 2. 克隆与安装
|
||
|
||
```bash
|
||
# 进入前端项目目录
|
||
cd step-web
|
||
# 安装依赖模块
|
||
npm install
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
复制环境模板并进行配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
此时你需要编辑 `.env` 文件：
|
||
- `APP_ADMIN_USERNAME`：登录用的管理员用户名（如 admin）
|
||
- `APP_ADMIN_PASSWORD_HASH`：登录用的明文密码或哈希值（本示例暂时为弱校验）
|
||
- `APP_SESSION_SECRET`：用于签署 Cookie，避免被篡改
|
||
- `STEP_BIN`：如果你本地安装的 step CLI 不在全局 `PATH`，请填写它的绝对路径（如 `/usr/bin/step`）。
|
||
- `STEP_CONTEXT`：所使用的 step context 配置名称。
|
||
- `STEP_CA_URL`：如果存在独立通信地址的主 ca 节点，请在此提供（如 `https://ca.local:8443`）。
|
||
|
||
### 4. 数据库初始化
|
||
|
||
初始化 SQLite 数据库及创建必要的表结构（`certificates`, `audit_logs`）：
|
||
|
||
```bash
|
||
npx tsx scripts/init-db.ts
|
||
```
|
||
> 如果系统提示未识别此命令，请先执行 `npm i -g tsx`。执行成功后，`data/app.db` 会被创建。
|
||
|
||
### 5. 启动本地开发服务
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
打开浏览器访问 `http://localhost:5173`，使用 `.env` 中的账密尝试登录和测试发证。
|
||
|
||
---
|
||
|
||
## 🚀 生产环境部署 (Node Adapter)
|
||
|
||
项目使用了 SvelteKit 的 `@sveltejs/adapter-node`，因此最终输出的是标准的 Node.js 应用进程。
|
||
|
||
### 1. 构建应用
|
||
|
||
在开发机或者 CI/CD 流程中执行：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
这会在 `.svelte-kit/` 与最终的 `build/` 目录下生成产物。
|
||
|
||
### 2. 服务器部署步骤
|
||
|
||
1. 将项目源码（不包括 `node_modules`）和 `build/` 目录上传到服务器（如 Linux Ubuntu/Debian 服务器）。
|
||
2. 在服务器上准备与 `.env` 中相符的 `step-ca` 环境，确保 `step` 拥有足够的权限读写你设置的 `STEP_OUTPUT_DIR`。
|
||
3. 执行 `npm install --omit=dev` 仅安装生产依赖（主要为了安装适配器需要的依赖如 `better-sqlite3`）。
|
||
4. 在服务运行前同样需要初始化数据库结构（如果你没上传旧有的 `data/app.db`），可以执行 `npx tsx scripts/init-db.ts`。
|
||
|
||
### 3. 运行服务 (使用 PM2 / Systemd)
|
||
|
||
#### Systemd 配置示例
|
||
|
||
创建一个 Systemd 守护进程监控这个 Web 应用运行：
|
||
|
||
```ini
|
||
# /etc/systemd/system/step-admin.service
|
||
[Unit]
|
||
Description=Step CA Admin Web Dashboard
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=your-node-user
|
||
# 切换到你的项目目录
|
||
WorkingDirectory=/var/www/step-admin
|
||
# 指定 NODE_ENV 与加载对应的环境变量文件
|
||
Environment="NODE_ENV=production"
|
||
EnvironmentFile=/var/www/step-admin/.env
|
||
# 启动执行 build 后的入口
|
||
ExecStart=/usr/bin/node build/index.js
|
||
Restart=on-failure
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
执行命令启动：
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now step-admin
|
||
```
|
||
|
||
默认它会在本机的 `3000` 端口启动服务。
|
||
|
||
### 4. 配置反向代理 (Caddy 示例)
|
||
|
||
建议Web 后台不直接走公网裸奔，通过 Caddy 代理加上 HTTPS 支持更为安全可靠：
|
||
|
||
```caddyfile
|
||
admin.ca.example.com {
|
||
reverse_proxy localhost:3000
|
||
}
|
||
```
|
||
|
||
重新加载 Caddy：`systemctl reload caddy`
|
||
|
||
---
|
||
|
||
## ⚠️ 安全与使用须知
|
||
- 此后台的核心功能是在服务器本地利用 child process 调用 `step` 客户端。务必注意权限控制，不要使用 `root` 用户运行这个后台服务。尽量给予一个权限克制的专门系统账户，并只开放该用户对于 `step-ca` 相关凭证目录（以及 `STEP_OUTPUT_DIR`）的存取权限。
|
||
- Web 登录认证目前为简单实现，如用于复杂组织，请进一步对接 OIDC 或加强安全散列算法。
|