完成Scert首轮基础骨架开发与复审

This commit is contained in:
xuans committed 2026-08-26 10:34:04 +08:00
commit fd8d8608f5
41 files changed
+6987

No files matched your search

+4
View File
@@ -0,0 +1,4 @@
backend/dist/
frontend/node_modules/
frontend/dist/
*.log
+31
View File
@@ -0,0 +1,31 @@
# Scert 项目
Scert 是一个统一管理 SSL 证书、自动续期并部署到多台服务器的跨平台项目。
## 项目目录
- `backend`:Go 核心服务、CLI、数据库和 HTTP API。
- `frontend`:Vue Web 管理界面占位结构。
- `doc`:需求确认、技术架构和开发任务清单。
## 开发基线
- 第一阶段使用 Let’s Encrypt + `go-acme/lego`。
- 第一阶段包含单域名、泛域名和多域名 SAN。
- 支持 MySQL 5.7、MySQL 8.0 和 SQLite。
- HTTPS 采用默认核心服务终止、高级反向代理终止的双模式设计。
- CLI、Web 和桌面版共享核心服务、配置和数据。
## 开发状态
首轮基础骨架已经完成并等待复审。当前已完成配置、日志、数据库迁移、域名 Repository、基础 HTTP API、CLI 和前端占位页面;完整证书生命周期功能按 `doc/Scert开发任务清单.md` 继续开发。
详细内容请先阅读:
- `doc/SSL服务程序需求确认文档.md`
- `doc/SSL服务程序技术架构设计文档.md`
- `doc/Scert开发任务清单.md`
## 首轮复审状态
2026 年 8 月 26 日已完成首轮代码复审。基础骨架、SQLite、CLI、HTTP、前端生产构建和 Windows/Linux amd64 构建已通过;MySQL 5.7/8.0 真实实例测试因缺少明确连接参数保持阻塞。详细记录以 `doc/Scert开发任务清单.md` 的“二十七、首轮开发复审记录”为准。
+71
View File
@@ -0,0 +1,71 @@
# Scert
Scert 是面向 Windows 和 Linux 的 SSL 证书管理服务。当前代码处于首轮基础骨架阶段,已建立配置、数据库、日志、CLI、HTTP API 和前端占位结构。
## 当前已实现
- Go 后端模块和 `scert` CLI 入口。
- JSON 配置生成、读取、校验和原子保存。
- Windows 与 Linux 默认目录模型。
- SQLite 和 MySQL 数据库连接抽象。
- SQLite/MySQL 首版迁移脚本。
- 域名基础模型与 Repository。
- 健康检查、状态和域名基础 API。
- 中文 CLI:`version`、`help`、`init`、`status`、`serve`、`domain list`、`domain add`。
- Vue 前端状态占位页面。
## 首轮运行
在 `backend` 目录执行:
```powershell
go run ./cmd/scert init --base-dir C:\ScertData
go run ./cmd/scert status --base-dir C:\ScertData
go run ./cmd/scert domain add --base-dir C:\ScertData --name example.com --type single
go run ./cmd/scert domain list --base-dir C:\ScertData
go run ./cmd/scert serve --base-dir C:\ScertData
```
服务启动后可访问:
- `GET /healthz`
- `GET /api/v1/status`
- `GET /api/v1/domains`
- `POST /api/v1/domains`
- `DELETE /api/v1/domains/:id`
当前 `serve` 是 HTTP 基础骨架。HTTPS 双模式、ACME 证书申请、DNS-01、远程部署等功能按开发任务清单在后续阶段实现。
## 测试和构建
```powershell
go fmt ./...
go test ./...
go build -o dist/scert.exe ./cmd/scert
```
Linux amd64 交叉编译:
```powershell
$env:GOOS = 'linux'
$env:GOARCH = 'amd64'
go build -o dist/scert-linux-amd64 ./cmd/scert
Remove-Item Env:GOOS
Remove-Item Env:GOARCH
```
## 数据库说明
- SQLite 用于单机、桌面和开发测试模式。
- MySQL 5.7 是基础开发和最低兼容版本。
- MySQL 8.0 用于兼容性测试。
- 数据库密码不得写入 Git、脚本参数或日志。
- MySQL 客户端和服务实例必须使用明确路径、端口和 DSN,不能通过 PATH 中的单个 `mysql` 命令判断版本。
## 当前未实现
ACME/lego 实际申请、DNS 服务商 API、自动续期、SSH/SFTP 部署、Nginx/Caddy/Apache reload、完整 Web 管理界面、Wails 桌面版、Windows Service 和 Linux systemd 均未在首轮基础骨架中宣称完成。
## 首轮复审状态
2026 年 8 月 26 日已完成首轮代码复审。`gofmt`、`go vet`、`go test`、竞态检测、Windows amd64 构建、Linux amd64 交叉构建、CLI 和 HTTP 实际流程均通过。MySQL 5.7/8.0 仅完成代码层实现和客户端版本确认,真实实例连接与迁移仍需明确 DSN、端口和凭据后验证。
+7
View File
@@ -0,0 +1,7 @@
package main
import "git.pcux.cn/xuans/Scert/backend/internal/cli"
func main() {
cli.Execute()
}
+50
View File
@@ -0,0 +1,50 @@
module git.pcux.cn/xuans/Scert/backend
go 1.26.0
require (
github.com/gin-gonic/gin v1.10.1
github.com/go-sql-driver/mysql v1.9.3
github.com/spf13/cobra v1.10.1
modernc.org/sqlite v1.37.0
)
require (
filippo.io/edwards25519 v1.1.0 // indirect
github.com/bytedance/sonic v1.11.6 // indirect
github.com/bytedance/sonic/loader v0.1.1 // indirect
github.com/cloudwego/base64x v0.1.4 // indirect
github.com/cloudwego/iasm v0.2.0 // indirect
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/gabriel-vasile/mimetype v1.4.3 // indirect
github.com/gin-contrib/sse v0.1.0 // indirect
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/go-playground/validator/v10 v10.20.0 // indirect
github.com/goccy/go-json v0.10.2 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/klauspost/cpuid/v2 v2.2.7 // indirect
github.com/leodido/go-urn v1.4.0 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
github.com/modern-go/reflect2 v1.0.2 // indirect
github.com/ncruces/go-strftime v0.1.9 // indirect
github.com/pelletier/go-toml/v2 v2.2.2 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/spf13/pflag v1.0.9 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.2.12 // indirect
golang.org/x/arch v0.8.0 // indirect
golang.org/x/crypto v0.23.0 // indirect
golang.org/x/exp v0.0.0-20250305212735-054e65f0b394 // indirect
golang.org/x/net v0.25.0 // indirect
golang.org/x/sys v0.31.0 // indirect
golang.org/x/text v0.15.0 // indirect
google.golang.org/protobuf v1.34.1 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
modernc.org/libc v1.62.1 // indirect
modernc.org/mathutil v1.7.1 // indirect
modernc.org/memory v1.9.1 // indirect
)
+141
View File
@@ -0,0 +1,141 @@
filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
github.com/bytedance/sonic v1.11.6 h1:oUp34TzMlL+OY1OUWxHqsdkgC/Zfc85zGqw9siXjrc0=
github.com/bytedance/sonic v1.11.6/go.mod h1:LysEHSvpvDySVdC2f87zGWf6CIKJcAvqab1ZaiQtds4=
github.com/bytedance/sonic/loader v0.1.1 h1:c+e5Pt1k/cy5wMveRDyk2X4B9hF4g7an8N3zCYjJFNM=
github.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=
github.com/cloudwego/base64x v0.1.4 h1:jwCgWpFanWmN8xoIUHa2rtzmkd5J2plF/dnLS6Xd/0Y=
github.com/cloudwego/base64x v0.1.4/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
github.com/cloudwego/iasm v0.2.0 h1:1KNIy1I1H9hNNFEEH3DVnI4UujN+1zjpuk6gwHLTssg=
github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
github.com/gin-gonic/gin v1.10.1/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBExVwjEviJTixqxL8=
github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
github.com/klauspost/cpuid/v2 v2.2.7 h1:ZWSB3igEs+d0qvnxR/ZBzXVmxkgt8DdzP6m9pfuVLDM=
github.com/klauspost/cpuid/v2 v2.2.7/go.mod h1:Lcz8mBdAVJIBVzewtcLocK12l3Y+JytZYpaMropDUws=
github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
golang.org/x/crypto v0.23.0 h1:dIJU/v2J8Mdglj/8rJ6UUOM3Zc9zLZxVZwwxMooUSAI=
golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
golang.org/x/exp v0.0.0-20250305212735-054e65f0b394 h1:nDVHiLt8aIbd/VzvPWN6kSOPE7+F/fNFDSXLVYkE/Iw=
golang.org/x/exp v0.0.0-20250305212735-054e65f0b394/go.mod h1:sIifuuw/Yco/y6yb6+bDNfyeQ/MdPUy/hKEMYQV17cM=
golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU=
golang.org/x/mod v0.24.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/tools v0.31.0 h1:0EedkvKDbh+qistFTd0Bcwe/YLh4vHwWEkiI0toFIBU=
golang.org/x/tools v0.31.0/go.mod h1:naFTU+Cev749tSJRXJlna0T3WxKvb1kWEx15xA4SdmQ=
google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
modernc.org/cc/v4 v4.25.2 h1:T2oH7sZdGvTaie0BRNFbIYsabzCxUQg8nLqCdQ2i0ic=
modernc.org/cc/v4 v4.25.2/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
modernc.org/ccgo/v4 v4.25.1 h1:TFSzPrAGmDsdnhT9X2UrcPMI3N/mJ9/X9ykKXwLhDsU=
modernc.org/ccgo/v4 v4.25.1/go.mod h1:njjuAYiPflywOOrm3B7kCB444ONP5pAVr8PIEoE0uDw=
modernc.org/fileutil v1.3.0 h1:gQ5SIzK3H9kdfai/5x41oQiKValumqNTDXMvKo62HvE=
modernc.org/fileutil v1.3.0/go.mod h1:XatxS8fZi3pS8/hKG2GH/ArUogfxjpEKs3Ku3aK4JyQ=
modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
modernc.org/libc v1.62.1 h1:s0+fv5E3FymN8eJVmnk0llBe6rOxCu/DEU+XygRbS8s=
modernc.org/libc v1.62.1/go.mod h1:iXhATfJQLjG3NWy56a6WVU73lWOcdYVxsvwCgoPljuo=
modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
modernc.org/memory v1.9.1 h1:V/Z1solwAVmMW1yttq3nDdZPJqV1rM05Ccq6KMSZ34g=
modernc.org/memory v1.9.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
modernc.org/sqlite v1.37.0 h1:s1TMe7T3Q3ovQiK2Ouz4Jwh7dw4ZDqbebSDTlSJdfjI=
modernc.org/sqlite v1.37.0/go.mod h1:5YiWv+YviqGMuGw4V+PNplcyaJ5v+vQd7TQOgkACoJM=
modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=
+79
View File
@@ -0,0 +1,79 @@
package app
import (
"context"
"fmt"
"log/slog"
"time"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/database"
"git.pcux.cn/xuans/Scert/backend/internal/httpapi"
"git.pcux.cn/xuans/Scert/backend/internal/logging"
"git.pcux.cn/xuans/Scert/backend/internal/repository"
)
type App struct {
Config config.Config
Logger *logging.Logger
Database *database.Database
Repository *repository.SQLDomainRepository
HTTP *httpapi.Server
}
func New(ctx context.Context, cfg config.Config) (*App, error) {
if err := cfg.Validate(); err != nil {
return nil, err
}
for _, path := range []string{cfg.Paths.Install, cfg.Paths.Certificate, cfg.Paths.Config, cfg.Paths.Data, cfg.Paths.Log, cfg.Paths.Backup} {
if err := makeDirectory(path); err != nil {
return nil, fmt.Errorf("创建运行目录失败:%w", err)
}
}
logger, err := logging.New(cfg.Paths.Log, slog.LevelInfo)
if err != nil {
return nil, fmt.Errorf("初始化日志失败:%w", err)
}
db, err := database.Open(ctx, cfg.Database)
if err != nil {
_ = logger.Close()
return nil, err
}
if err := database.Migrate(ctx, db.DB, cfg.Database.Driver); err != nil {
_ = db.Close()
_ = logger.Close()
return nil, err
}
repo := repository.NewSQLDomainRepository(db.DB)
server := httpapi.New(httpapi.Dependencies{Config: cfg, Logger: logger, Repository: repo})
return &App{Config: cfg, Logger: logger, Database: db, Repository: repo, HTTP: server}, nil
}
func (a *App) Close() error {
if a == nil {
return nil
}
var first error
if a.HTTP != nil {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
if err := a.HTTP.Shutdown(ctx); err != nil && first == nil {
first = err
}
cancel()
}
if a.Database != nil {
if err := a.Database.Close(); err != nil && first == nil {
first = err
}
}
if a.Logger != nil {
if err := a.Logger.Close(); err != nil && first == nil {
first = err
}
}
return first
}
func makeDirectory(path string) error {
return osMkdirAll(path)
}
+7
View File
@@ -0,0 +1,7 @@
package app
import "os"
var osMkdirAll = func(path string) error {
return os.MkdirAll(path, 0o750)
}
+3
View File
@@ -0,0 +1,3 @@
package buildinfo
const Version = "0.1.0"
+234
View File
@@ -0,0 +1,234 @@
package cli
import (
"encoding/json"
"errors"
"fmt"
"net/http"
"os"
"os/signal"
"path/filepath"
"strings"
"syscall"
"github.com/spf13/cobra"
"git.pcux.cn/xuans/Scert/backend/internal/app"
"git.pcux.cn/xuans/Scert/backend/internal/buildinfo"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
)
const version = buildinfo.Version
var (
configPath string
baseDir string
)
const helpTemplate = `{{with (or .Long .Short)}}{{. | trimTrailingWhitespaces}}{{end}}
用法:
{{.UseLine}}{{if .HasAvailableSubCommands}}
可用命令:
{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}} {{rpad .Name .NamePadding }} {{.Short}}{{"\n"}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
参数:
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
全局参数:
{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
其他帮助:
{{.CommandPath}} help [命令]{{end}}
`
func Execute() {
if err := newRootCommand().Execute(); err != nil {
fmt.Fprintln(os.Stderr, "错误:", err)
os.Exit(1)
}
}
func newRootCommand() *cobra.Command {
root := &cobra.Command{Use: "scert", Short: "SSL 证书管理服务", SilenceUsage: true}
root.CompletionOptions.DisableDefaultCmd = true
root.SetHelpCommand(newHelpCommand())
root.SetHelpTemplate(helpTemplate)
root.PersistentFlags().StringVar(&configPath, "config", "", "配置文件路径")
root.PersistentFlags().StringVar(&baseDir, "base-dir", "", "Windows 默认安装根目录")
root.AddCommand(
&cobra.Command{Use: "version", Short: "显示版本信息", Run: func(cmd *cobra.Command, args []string) { cmd.Printf("Scert %s\n", version) }},
newInitCommand(), newStatusCommand(), newServeCommand(), newDomainCommand(),
)
localizeHelpFlags(root)
return root
}
func newHelpCommand() *cobra.Command {
return &cobra.Command{
Use: "help [命令]",
Short: "显示帮助信息",
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) == 0 {
return cmd.Root().Help()
}
target, remaining, err := cmd.Root().Find(args)
if err != nil {
return err
}
if len(remaining) > 0 {
return fmt.Errorf("未知命令:%s", strings.Join(remaining, " "))
}
return target.Help()
},
}
}
func localizeHelpFlags(command *cobra.Command) {
command.DisableFlagsInUseLine = true
command.InitDefaultHelpFlag()
if flag := command.Flags().Lookup("help"); flag != nil {
flag.Usage = "显示帮助信息"
}
for _, child := range command.Commands() {
localizeHelpFlags(child)
}
}
func newInitCommand() *cobra.Command {
return &cobra.Command{Use: "init", Short: "生成初始配置", RunE: func(cmd *cobra.Command, args []string) error {
path := resolveConfigPath()
if _, err := os.Stat(path); err == nil {
return fmt.Errorf("配置文件已存在:%s", path)
} else if !errors.Is(err, os.ErrNotExist) {
return err
}
cfg := config.Default(baseDir)
if err := cfg.Save(path); err != nil {
return err
}
fmt.Printf("初始配置已生成:%s\n", path)
fmt.Println("当前默认使用 ACME Staging 环境,完成 DNS 配置后再切换 Production。")
return nil
}}
}
func newStatusCommand() *cobra.Command {
return &cobra.Command{Use: "status", Short: "查看服务状态", RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := loadConfig()
if err != nil {
return err
}
return printJSON(cmd, commandStatus(cfg))
}}
}
func commandStatus(cfg config.Config) map[string]any {
return map[string]any{"service": "scert", "version": buildinfo.Version, "config_version": cfg.Version, "setup_ready": cfg.SetupReady, "https_mode": cfg.Server.HTTPSMode, "database_driver": cfg.Database.Driver}
}
func newServeCommand() *cobra.Command {
return &cobra.Command{Use: "serve", Short: "启动 Web 服务", RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := loadConfig()
if err != nil {
return err
}
service, err := app.New(cmd.Context(), cfg)
if err != nil {
return err
}
defer service.Close()
ctx, stop := signal.NotifyContext(cmd.Context(), os.Interrupt, syscall.SIGTERM)
defer stop()
errCh := make(chan error, 1)
go func() { errCh <- service.HTTP.ListenAndServe() }()
select {
case <-ctx.Done():
return nil
case err := <-errCh:
if errors.Is(err, http.ErrServerClosed) {
return nil
}
return err
}
}}
}
func newDomainCommand() *cobra.Command {
command := &cobra.Command{Use: "domain", Short: "管理托管域名"}
command.AddCommand(newDomainListCommand(), newDomainAddCommand())
return command
}
func newDomainListCommand() *cobra.Command {
return &cobra.Command{Use: "list", Short: "查看域名列表", RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := loadConfig()
if err != nil {
return err
}
service, err := app.New(cmd.Context(), cfg)
if err != nil {
return err
}
defer service.Close()
items, err := service.Repository.List(cmd.Context())
if err != nil {
return err
}
return printJSON(cmd, items)
}}
}
func newDomainAddCommand() *cobra.Command {
var name, certificateType string
var sans []string
command := &cobra.Command{Use: "add", Short: "添加托管域名", RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := loadConfig()
if err != nil {
return err
}
service, err := app.New(cmd.Context(), cfg)
if err != nil {
return err
}
defer service.Close()
item, err := domain.NewDomain(name, domain.CertificateType(certificateType), sans)
if err != nil {
return err
}
if err := service.Repository.Create(cmd.Context(), item); err != nil {
return err
}
fmt.Printf("域名已添加:%s\n", item.Name)
return nil
}}
command.Flags().StringVar(&name, "name", "", "域名")
command.Flags().StringVar(&certificateType, "type", string(domain.CertificateSingle), "证书类型:single、wildcard、san")
command.Flags().StringSliceVar(&sans, "sans", nil, "SAN 域名列表")
_ = command.MarkFlagRequired("name")
return command
}
func printJSON(cmd *cobra.Command, value any) error {
data, err := json.MarshalIndent(value, "", " ")
if err != nil {
return fmt.Errorf("编码 JSON 失败:%w", err)
}
_, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
return err
}
func loadConfig() (config.Config, error) {
path := resolveConfigPath()
return config.Load(path)
}
func resolveConfigPath() string {
if configPath != "" {
return configPath
}
paths := config.DefaultPaths(baseDir)
return filepath.Join(paths.Config, "scert.json")
}
+60
View File
@@ -0,0 +1,60 @@
package cli
import (
"bytes"
"strings"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/buildinfo"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
func TestHelpIsLocalizedAndHasNoDuplicateCommands(t *testing.T) {
configPath = ""
baseDir = ""
root := newRootCommand()
var output bytes.Buffer
root.SetOut(&output)
root.SetErr(&output)
root.SetArgs([]string{"help"})
if err := root.Execute(); err != nil {
t.Fatalf("执行帮助命令失败:%v", err)
}
text := output.String()
for _, expected := range []string{"用法:", "可用命令:", "参数:"} {
if !strings.Contains(text, expected) {
t.Fatalf("帮助缺少中文标题 %q:%s", expected, text)
}
}
for _, unexpected := range []string{"Available Commands:", "Usage:", "Flags:", "completion"} {
if strings.Contains(text, unexpected) {
t.Fatalf("帮助仍包含未本地化或禁用内容 %q:%s", unexpected, text)
}
}
if strings.Count(text, "\n help ") != 1 {
t.Fatalf("help 命令数量不正确:%s", text)
}
}
func TestHelpSupportsSubcommand(t *testing.T) {
root := newRootCommand()
var output bytes.Buffer
root.SetOut(&output)
root.SetErr(&output)
root.SetArgs([]string{"help", "domain"})
if err := root.Execute(); err != nil {
t.Fatalf("查看子命令帮助失败:%v", err)
}
text := output.String()
if !strings.Contains(text, "管理托管域名") || !strings.Contains(text, "添加托管域名") {
t.Fatalf("子命令帮助内容不正确:%s", text)
}
}
func TestCommandStatusUsesApplicationVersion(t *testing.T) {
cfg := config.Default(t.TempDir())
status := commandStatus(cfg)
if status["version"] != buildinfo.Version || status["config_version"] != config.CurrentVersion {
t.Fatalf("状态版本字段不正确:%+v", status)
}
}
+183
View File
@@ -0,0 +1,183 @@
package config
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
"runtime"
"strings"
)
const CurrentVersion = 1
const ConfigFormat = "json"
type Config struct {
Version int `json:"version"`
SetupReady bool `json:"setup_ready"`
Server ServerConfig `json:"server"`
Database DatabaseConfig `json:"database"`
Paths PathsConfig `json:"paths"`
ACME ACMEConfig `json:"acme"`
Notification NotificationConfig `json:"notification"`
}
type ServerConfig struct {
Host string `json:"host"`
Port int `json:"port"`
HTTPSMode string `json:"https_mode"`
}
type DatabaseConfig struct {
Driver string `json:"driver"`
DSN string `json:"dsn"`
MaxOpenConns int `json:"max_open_conns"`
MaxIdleConns int `json:"max_idle_conns"`
ConnMaxLifetimeMins int `json:"conn_max_lifetime_mins"`
}
type PathsConfig struct {
Install string `json:"install"`
Certificate string `json:"certificate"`
Config string `json:"config"`
Data string `json:"data"`
Log string `json:"log"`
Backup string `json:"backup"`
}
type ACMEConfig struct {
CA string `json:"ca"`
Environment string `json:"environment"`
AccountEmail string `json:"account_email"`
RenewalThresholdDays int `json:"renewal_threshold_days"`
}
type NotificationConfig struct {
HTTPEnabled bool `json:"http_enabled"`
SMTPEnabled bool `json:"smtp_enabled"`
TimeoutSecs int `json:"timeout_secs"`
RetryCount int `json:"retry_count"`
}
func Default(baseDir string) Config {
paths := DefaultPaths(baseDir)
return Config{
Version: CurrentVersion,
SetupReady: false,
Server: ServerConfig{Host: "127.0.0.1", Port: 8080, HTTPSMode: "direct"},
Database: DatabaseConfig{
Driver: "sqlite", DSN: filepath.Join(paths.Data, "scert.db"),
MaxOpenConns: 4, MaxIdleConns: 2, ConnMaxLifetimeMins: 30,
},
Paths: paths,
ACME: ACMEConfig{CA: "letsencrypt", Environment: "staging", RenewalThresholdDays: 6},
Notification: NotificationConfig{TimeoutSecs: 10, RetryCount: 3},
}
}
func DefaultPaths(baseDir string) PathsConfig {
if runtime.GOOS == "linux" {
return PathsConfig{
Install: "/scert", Certificate: "/ssl", Config: "/scert/conf",
Data: "/scert/data", Log: "/scert/log", Backup: "/scert/backups",
}
}
if strings.TrimSpace(baseDir) == "" {
baseDir = "."
}
install := filepath.Join(baseDir, "Scert")
return PathsConfig{
Install: install, Certificate: filepath.Join(install, "ssl"),
Config: filepath.Join(install, "config"), Data: filepath.Join(install, "data"),
Log: filepath.Join(install, "logs"), Backup: filepath.Join(install, "backups"),
}
}
func Load(path string) (Config, error) {
data, err := os.ReadFile(path)
if err != nil {
return Config{}, fmt.Errorf("读取配置文件失败:%w", err)
}
var cfg Config
if err := json.Unmarshal(data, &cfg); err != nil {
return Config{}, fmt.Errorf("解析配置文件失败:%w", err)
}
if err := cfg.Validate(); err != nil {
return Config{}, err
}
return cfg, nil
}
func (c Config) Save(path string) error {
if err := c.Validate(); err != nil {
return err
}
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
return fmt.Errorf("创建配置目录失败:%w", err)
}
data, err := json.MarshalIndent(c, "", " ")
if err != nil {
return fmt.Errorf("编码配置失败:%w", err)
}
data = append(data, '\n')
tmpPath := path + ".tmp"
if err := os.WriteFile(tmpPath, data, 0o600); err != nil {
return fmt.Errorf("写入临时配置文件失败:%w", err)
}
if err := os.Rename(tmpPath, path); err != nil {
_ = os.Remove(tmpPath)
return fmt.Errorf("替换配置文件失败:%w", err)
}
if err := os.Chmod(path, 0o600); err != nil {
return fmt.Errorf("设置配置文件权限失败:%w", err)
}
return nil
}
func (c Config) Validate() error {
if c.Version != CurrentVersion {
return fmt.Errorf("配置版本不兼容:%d", c.Version)
}
if strings.TrimSpace(c.Server.Host) == "" {
return fmt.Errorf("服务监听地址不能为空")
}
if c.Server.Port < 1 || c.Server.Port > 65535 {
return fmt.Errorf("服务监听端口无效:%d", c.Server.Port)
}
if c.Server.HTTPSMode != "direct" && c.Server.HTTPSMode != "proxy" {
return fmt.Errorf("HTTPS 模式无效:%s", c.Server.HTTPSMode)
}
if c.Database.Driver != "sqlite" && c.Database.Driver != "mysql" {
return fmt.Errorf("数据库驱动无效:%s", c.Database.Driver)
}
if strings.TrimSpace(c.Database.DSN) == "" {
return fmt.Errorf("数据库连接信息不能为空")
}
if c.Database.MaxOpenConns < 1 || c.Database.MaxIdleConns < 0 || c.Database.MaxIdleConns > c.Database.MaxOpenConns {
return fmt.Errorf("数据库连接池配置无效")
}
if c.Database.ConnMaxLifetimeMins < 0 {
return fmt.Errorf("数据库连接生命周期不能为负数")
}
for name, value := range map[string]string{
"安装目录": c.Paths.Install, "证书目录": c.Paths.Certificate, "配置目录": c.Paths.Config,
"数据目录": c.Paths.Data, "日志目录": c.Paths.Log, "备份目录": c.Paths.Backup,
} {
if strings.TrimSpace(value) == "" {
return fmt.Errorf("%s不能为空", name)
}
}
if c.ACME.CA != "letsencrypt" {
return fmt.Errorf("当前仅支持 Let's Encrypt")
}
if c.ACME.Environment != "staging" && c.ACME.Environment != "production" {
return fmt.Errorf("ACME 环境无效:%s", c.ACME.Environment)
}
if c.ACME.RenewalThresholdDays < 1 {
return fmt.Errorf("续期阈值必须大于 0")
}
if c.Notification.TimeoutSecs < 1 || c.Notification.RetryCount < 0 {
return fmt.Errorf("通知配置无效")
}
return nil
}
+44
View File
@@ -0,0 +1,44 @@
package config
import (
"path/filepath"
"runtime"
"testing"
)
func TestDefaultPaths(t *testing.T) {
paths := DefaultPaths(t.TempDir())
if runtime.GOOS == "linux" {
if paths.Install != "/scert" || paths.Certificate != "/ssl" {
t.Fatalf("Linux 默认路径不正确:%+v", paths)
}
return
}
if filepath.Base(paths.Install) != "Scert" || filepath.Base(paths.Certificate) != "ssl" {
t.Fatalf("Windows 默认路径不正确:%+v", paths)
}
}
func TestSaveAndLoad(t *testing.T) {
dir := t.TempDir()
cfg := Default(dir)
path := filepath.Join(dir, "config", "scert.json")
if err := cfg.Save(path); err != nil {
t.Fatalf("保存配置失败:%v", err)
}
loaded, err := Load(path)
if err != nil {
t.Fatalf("读取配置失败:%v", err)
}
if loaded.Version != cfg.Version || loaded.Database.Driver != "sqlite" {
t.Fatalf("读取配置内容不一致:%+v", loaded)
}
}
func TestValidateRejectsInvalidPort(t *testing.T) {
cfg := Default(t.TempDir())
cfg.Server.Port = 70000
if err := cfg.Validate(); err == nil {
t.Fatal("无效端口未被拒绝")
}
}
+45
View File
@@ -0,0 +1,45 @@
package config
import (
"os"
"path/filepath"
"runtime"
"testing"
)
func TestValidateRejectsIncompatibleVersion(t *testing.T) {
cfg := Default(t.TempDir())
cfg.Version = CurrentVersion + 1
if err := cfg.Validate(); err == nil {
t.Fatal("不兼容配置版本未被拒绝")
}
}
func TestSaveCanReplaceExistingConfig(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "config", "scert.json")
cfg := Default(dir)
if err := cfg.Save(path); err != nil {
t.Fatalf("首次保存配置失败:%v", err)
}
cfg.Server.Port = 9443
if err := cfg.Save(path); err != nil {
t.Fatalf("覆盖保存配置失败:%v", err)
}
loaded, err := Load(path)
if err != nil {
t.Fatalf("读取覆盖后的配置失败:%v", err)
}
if loaded.Server.Port != 9443 {
t.Fatalf("覆盖后的配置内容不正确:%d", loaded.Server.Port)
}
if runtime.GOOS != "windows" {
info, err := os.Stat(path)
if err != nil {
t.Fatalf("读取配置文件权限失败:%v", err)
}
if info.Mode().Perm() != 0o600 {
t.Fatalf("配置文件权限不正确:%o", info.Mode().Perm())
}
}
}
+90
View File
@@ -0,0 +1,90 @@
package database
import (
"context"
"database/sql"
"fmt"
"path/filepath"
"strings"
"time"
"github.com/go-sql-driver/mysql"
_ "modernc.org/sqlite"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
type Database struct {
DB *sql.DB
}
func Open(ctx context.Context, cfg config.DatabaseConfig) (*Database, error) {
if cfg.Driver != "sqlite" && cfg.Driver != "mysql" {
return nil, fmt.Errorf("数据库驱动无效:%s", cfg.Driver)
}
dsn := cfg.DSN
if cfg.Driver == "mysql" {
var err error
dsn, err = normalizeMySQLDSN(dsn)
if err != nil {
return nil, err
}
}
if cfg.Driver == "sqlite" {
if cfg.DSN != ":memory:" && len(cfg.DSN) > 0 && cfg.DSN != "file::memory:?cache=shared" {
if err := ensureSQLiteDir(cfg.DSN); err != nil {
return nil, err
}
}
}
db, err := sql.Open(cfg.Driver, dsn)
if err != nil {
return nil, fmt.Errorf("打开数据库失败:%w", err)
}
db.SetMaxOpenConns(cfg.MaxOpenConns)
db.SetMaxIdleConns(cfg.MaxIdleConns)
db.SetConnMaxLifetime(time.Duration(cfg.ConnMaxLifetimeMins) * time.Minute)
pingCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
if err := db.PingContext(pingCtx); err != nil {
_ = db.Close()
return nil, fmt.Errorf("连接数据库失败:%w", err)
}
return &Database{DB: db}, nil
}
func normalizeMySQLDSN(dsn string) (string, error) {
cfg, err := mysql.ParseDSN(dsn)
if err != nil {
return "", fmt.Errorf("解析 MySQL 连接信息失败:%w", err)
}
cfg.ParseTime = true
cfg.Loc = time.UTC
return cfg.FormatDSN(), nil
}
func ensureSQLiteDir(dsn string) error {
path := dsn
if strings.HasPrefix(path, "file:") {
path = strings.TrimPrefix(strings.SplitN(path, "?", 2)[0], "file:")
}
return osMkdirAll(filepath.Dir(path))
}
var osMkdirAll = func(path string) error {
if path == "." || path == "" {
return nil
}
return mkdirAll(path)
}
var mkdirAll = func(path string) error {
return makeDirectory(path)
}
func (d *Database) Close() error {
if d == nil || d.DB == nil {
return nil
}
return d.DB.Close()
}
@@ -0,0 +1,30 @@
package database
import (
"context"
"path/filepath"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
func TestOpenAndMigrateSQLite(t *testing.T) {
dir := t.TempDir()
cfg := config.Default(dir)
cfg.Database.DSN = filepath.Join(dir, "data", "test.db")
db, err := Open(context.Background(), cfg.Database)
if err != nil {
t.Fatalf("打开 SQLite 失败:%v", err)
}
defer db.Close()
if err := Migrate(context.Background(), db.DB, "sqlite"); err != nil {
t.Fatalf("SQLite 迁移失败:%v", err)
}
var count int
if err := db.DB.QueryRow("SELECT COUNT(*) FROM schema_migrations").Scan(&count); err != nil {
t.Fatalf("读取迁移版本失败:%v", err)
}
if count != 1 {
t.Fatalf("迁移版本数量错误:%d", count)
}
}
+7
View File
@@ -0,0 +1,7 @@
package database
import "os"
func makeDirectory(path string) error {
return os.MkdirAll(path, 0o750)
}
+97
View File
@@ -0,0 +1,97 @@
package database
import (
"context"
"database/sql"
"embed"
"fmt"
"strings"
)
//go:embed migrations/sqlite/0001_initial.sql migrations/mysql/0001_initial.sql
var migrationFiles embed.FS
func Migrate(ctx context.Context, db *sql.DB, driver string) error {
if db == nil {
return fmt.Errorf("数据库连接不能为空")
}
if driver != "sqlite" && driver != "mysql" {
return fmt.Errorf("数据库驱动无效:%s", driver)
}
if _, err := db.ExecContext(ctx, migrationTableSQL(driver)); err != nil {
return fmt.Errorf("创建迁移表失败:%w", err)
}
var version int
err := db.QueryRowContext(ctx, "SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1").Scan(&version)
if err != nil && err != sql.ErrNoRows {
return fmt.Errorf("读取迁移版本失败:%w", err)
}
if err == sql.ErrNoRows {
version = 0
}
if version >= 1 {
return nil
}
path := "migrations/sqlite/0001_initial.sql"
if driver == "mysql" {
path = "migrations/mysql/0001_initial.sql"
}
content, err := migrationFiles.ReadFile(path)
if err != nil {
return fmt.Errorf("读取迁移文件失败:%w", err)
}
statements := migrationStatements(content)
if driver == "mysql" {
for _, statement := range statements {
if _, err := db.ExecContext(ctx, statement); err != nil {
return fmt.Errorf("执行数据库迁移失败:%w", err)
}
}
if _, err := db.ExecContext(ctx, "INSERT INTO schema_migrations (version) VALUES (1)"); err != nil {
return fmt.Errorf("记录迁移版本失败:%w", err)
}
return nil
}
tx, err := db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("开始迁移事务失败:%w", err)
}
for _, statement := range statements {
if _, err := tx.ExecContext(ctx, statement); err != nil {
_ = tx.Rollback()
return fmt.Errorf("执行数据库迁移失败:%w", err)
}
}
if _, err := tx.ExecContext(ctx, "INSERT INTO schema_migrations (version) VALUES (1)"); err != nil {
_ = tx.Rollback()
return fmt.Errorf("记录迁移版本失败:%w", err)
}
if err := tx.Commit(); err != nil {
return fmt.Errorf("提交数据库迁移失败:%w", err)
}
return nil
}
func migrationStatements(content []byte) []string {
statements := make([]string, 0)
for _, statement := range strings.Split(string(content), ";") {
statement = strings.TrimSpace(statement)
if statement != "" {
statements = append(statements, statement)
}
}
return statements
}
func migrationTableSQL(driver string) string {
if driver == "mysql" {
return `CREATE TABLE IF NOT EXISTS schema_migrations (
version INT NOT NULL PRIMARY KEY,
applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
)`
}
return `CREATE TABLE IF NOT EXISTS schema_migrations (
version INTEGER NOT NULL PRIMARY KEY,
applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
)`
}
@@ -0,0 +1,39 @@
CREATE TABLE IF NOT EXISTS settings (
`key` VARCHAR(128) NOT NULL PRIMARY KEY,
`value` TEXT NOT NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS domains (
id VARCHAR(36) NOT NULL PRIMARY KEY,
name VARCHAR(253) NOT NULL UNIQUE,
certificate_type VARCHAR(32) NOT NULL,
sans_json TEXT NOT NULL,
status VARCHAR(32) NOT NULL,
expires_at DATETIME NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS tasks (
id VARCHAR(36) NOT NULL PRIMARY KEY,
domain_id VARCHAR(36) NOT NULL,
task_type VARCHAR(32) NOT NULL,
status VARCHAR(32) NOT NULL,
message TEXT NOT NULL,
started_at DATETIME NULL,
finished_at DATETIME NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
INDEX idx_tasks_domain_id (domain_id)
);
CREATE TABLE IF NOT EXISTS audit_logs (
id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
action VARCHAR(64) NOT NULL,
resource_type VARCHAR(64) NOT NULL,
resource_id VARCHAR(36) NOT NULL,
status VARCHAR(32) NOT NULL,
message TEXT NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
INDEX idx_audit_logs_created_at (created_at)
);
@@ -0,0 +1,37 @@
CREATE TABLE IF NOT EXISTS settings (
key TEXT NOT NULL PRIMARY KEY,
value TEXT NOT NULL,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS domains (
id TEXT NOT NULL PRIMARY KEY,
name TEXT NOT NULL UNIQUE,
certificate_type TEXT NOT NULL,
sans_json TEXT NOT NULL,
status TEXT NOT NULL,
expires_at DATETIME NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS tasks (
id TEXT NOT NULL PRIMARY KEY,
domain_id TEXT NOT NULL,
task_type TEXT NOT NULL,
status TEXT NOT NULL,
message TEXT NOT NULL,
started_at DATETIME NULL,
finished_at DATETIME NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE IF NOT EXISTS audit_logs (
id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
action TEXT NOT NULL,
resource_type TEXT NOT NULL,
resource_id TEXT NOT NULL,
status TEXT NOT NULL,
message TEXT NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
+68
View File
@@ -0,0 +1,68 @@
package database
import (
"context"
"path/filepath"
"testing"
"time"
"github.com/go-sql-driver/mysql"
"git.pcux.cn/xuans/Scert/backend/internal/config"
)
func TestOpenRejectsUnknownDriver(t *testing.T) {
cfg := config.Default(t.TempDir()).Database
cfg.Driver = "postgres"
cfg.DSN = "unused"
if _, err := Open(context.Background(), cfg); err == nil {
t.Fatal("未知数据库驱动未被拒绝")
}
}
func TestNormalizeMySQLDSNEnablesTimeParsing(t *testing.T) {
dsn, err := normalizeMySQLDSN("user:password@tcp(127.0.0.1:3306)/scert?charset=utf8mb4")
if err != nil {
t.Fatalf("规范化 MySQL DSN 失败:%v", err)
}
parsed, err := mysql.ParseDSN(dsn)
if err != nil {
t.Fatalf("解析规范化后的 MySQL DSN 失败:%v", err)
}
if !parsed.ParseTime || parsed.Loc != time.UTC {
t.Fatal("MySQL DSN 未启用时间解析或未使用 UTC")
}
}
func TestSQLiteMigrationIsIdempotentAndCreatesBaseTables(t *testing.T) {
dir := t.TempDir()
cfg := config.Default(dir).Database
cfg.DSN = filepath.Join(dir, "data", "review.db")
db, err := Open(context.Background(), cfg)
if err != nil {
t.Fatalf("打开 SQLite 失败:%v", err)
}
defer db.Close()
for i := 0; i < 2; i++ {
if err := Migrate(context.Background(), db.DB, "sqlite"); err != nil {
t.Fatalf("第 %d 次迁移失败:%v", i+1, err)
}
}
var versions int
if err := db.DB.QueryRow("SELECT COUNT(*) FROM schema_migrations").Scan(&versions); err != nil {
t.Fatalf("读取迁移版本失败:%v", err)
}
if versions != 1 {
t.Fatalf("重复迁移写入了多条版本记录:%d", versions)
}
var tables int
if err := db.DB.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name IN ('settings', 'domains', 'tasks', 'audit_logs')`).Scan(&tables); err != nil {
t.Fatalf("检查基础数据表失败:%v", err)
}
if tables != 4 {
t.Fatalf("基础数据表数量不正确:%d", tables)
}
if err := Migrate(context.Background(), db.DB, "postgres"); err == nil {
t.Fatal("未知迁移驱动未被拒绝")
}
}
+99
View File
@@ -0,0 +1,99 @@
package domain
import (
"crypto/rand"
"fmt"
"regexp"
"strings"
"time"
)
var domainPattern = regexp.MustCompile(`^(?i)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$`)
type CertificateType string
const (
CertificateSingle CertificateType = "single"
CertificateWildcard CertificateType = "wildcard"
CertificateSAN CertificateType = "san"
)
type Domain struct {
ID string `json:"id"`
Name string `json:"name"`
CertificateType CertificateType `json:"certificate_type"`
SANs []string `json:"sans"`
Status string `json:"status"`
ExpiresAt *time.Time `json:"expires_at,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
func NewDomain(name string, certificateType CertificateType, sans []string) (Domain, error) {
name = strings.ToLower(strings.TrimSpace(name))
if !IsValidName(name) {
return Domain{}, fmt.Errorf("域名格式无效:%s", name)
}
if certificateType != CertificateSingle && certificateType != CertificateWildcard && certificateType != CertificateSAN {
return Domain{}, fmt.Errorf("证书类型无效:%s", certificateType)
}
cleanSANs := normalizeSANs(sans)
if certificateType == CertificateSAN {
cleanSANs = normalizeSANs(append([]string{name}, cleanSANs...))
}
if certificateType == CertificateSAN && len(cleanSANs) < 2 {
return Domain{}, fmt.Errorf("SAN 证书至少需要两个域名")
}
for _, san := range cleanSANs {
if !IsValidName(san) {
_, err := NewDomain(san, CertificateSingle, nil)
return Domain{}, err
}
}
if certificateType != CertificateSAN {
cleanSANs = []string{name}
}
if certificateType == CertificateWildcard && !strings.HasPrefix(name, "*.") {
return Domain{}, fmt.Errorf("泛域名必须以 *. 开头")
}
if certificateType != CertificateWildcard && strings.HasPrefix(name, "*.") {
return Domain{}, fmt.Errorf("只有泛域名证书类型允许使用 *. 域名")
}
now := time.Now().UTC()
return Domain{ID: NewID(), Name: name, CertificateType: certificateType, SANs: cleanSANs, Status: "pending", CreatedAt: now, UpdatedAt: now}, nil
}
func IsValidName(name string) bool {
name = strings.TrimSpace(strings.ToLower(name))
if strings.HasPrefix(name, "*.") {
name = strings.TrimPrefix(name, "*.")
}
return domainPattern.MatchString(name)
}
func normalizeSANs(sans []string) []string {
seen := make(map[string]struct{}, len(sans))
result := make([]string, 0, len(sans))
for _, item := range sans {
item = strings.ToLower(strings.TrimSpace(item))
if item == "" {
continue
}
if _, ok := seen[item]; ok {
continue
}
seen[item] = struct{}{}
result = append(result, item)
}
return result
}
func NewID() string {
var b [16]byte
if _, err := rand.Read(b[:]); err != nil {
return fmt.Sprintf("%d", time.Now().UnixNano())
}
b[6] = (b[6] & 0x0f) | 0x40
b[8] = (b[8] & 0x3f) | 0x80
return fmt.Sprintf("%08x-%04x-%04x-%04x-%012x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}
+57
View File
@@ -0,0 +1,57 @@
package domain
import "testing"
func TestNewDomainTypes(t *testing.T) {
tests := []struct {
name string
domainName string
certificateType CertificateType
wantError bool
}{
{name: "单域名", domainName: "Example.COM", certificateType: CertificateSingle},
{name: "泛域名", domainName: "*.example.com", certificateType: CertificateWildcard},
{name: "泛域名缺少前缀", domainName: "example.com", certificateType: CertificateWildcard, wantError: true},
{name: "单域名使用泛域名", domainName: "*.example.com", certificateType: CertificateSingle, wantError: true},
{name: "非法证书类型", domainName: "example.com", certificateType: CertificateType("invalid"), wantError: true},
}
for _, item := range tests {
t.Run(item.name, func(t *testing.T) {
result, err := NewDomain(item.domainName, item.certificateType, nil)
if item.wantError {
if err == nil {
t.Fatal("预期返回错误,实际未返回")
}
return
}
if err != nil {
t.Fatalf("创建域名失败:%v", err)
}
if result.Name == "" || len(result.SANs) != 1 || result.SANs[0] != result.Name {
t.Fatalf("域名规范化结果不正确:%+v", result)
}
})
}
}
func TestNewDomainSANIncludesPrimaryAndDeduplicates(t *testing.T) {
result, err := NewDomain("Example.com", CertificateSAN, []string{"www.example.com", "EXAMPLE.COM", "www.example.com"})
if err != nil {
t.Fatalf("创建 SAN 域名失败:%v", err)
}
if len(result.SANs) != 2 {
t.Fatalf("SAN 去重结果不正确:%v", result.SANs)
}
if result.SANs[0] != "example.com" || result.SANs[1] != "www.example.com" {
t.Fatalf("SAN 未自动包含主域名或顺序异常:%v", result.SANs)
}
}
func TestNewDomainSANValidation(t *testing.T) {
if _, err := NewDomain("example.com", CertificateSAN, []string{"example.com"}); err == nil {
t.Fatal("仅包含主域名的 SAN 配置未被拒绝")
}
if _, err := NewDomain("example.com", CertificateSAN, []string{"bad_domain"}); err == nil {
t.Fatal("非法 SAN 域名未被拒绝")
}
}
+104
View File
@@ -0,0 +1,104 @@
package httpapi
import (
"context"
"database/sql"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strings"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/buildinfo"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
)
type stubDomainRepository struct {
items []domain.Domain
created domain.Domain
listErr error
createErr error
deleteErr error
}
func (r *stubDomainRepository) Create(_ context.Context, item domain.Domain) error {
r.created = item
return r.createErr
}
func (r *stubDomainRepository) GetByID(_ context.Context, _ string) (domain.Domain, error) {
return domain.Domain{}, sql.ErrNoRows
}
func (r *stubDomainRepository) List(_ context.Context) ([]domain.Domain, error) {
return r.items, r.listErr
}
func (r *stubDomainRepository) Delete(_ context.Context, _ string) error {
return r.deleteErr
}
func TestStatusReturnsApplicationAndConfigVersions(t *testing.T) {
cfg := config.Default(t.TempDir())
server := New(Dependencies{Config: cfg, Repository: &stubDomainRepository{}})
response := httptest.NewRecorder()
server.Handler().ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/v1/status", nil))
if response.Code != http.StatusOK {
t.Fatalf("状态接口响应错误:%d", response.Code)
}
var payload struct {
Version string `json:"version"`
ConfigVersion int `json:"config_version"`
}
if err := json.Unmarshal(response.Body.Bytes(), &payload); err != nil {
t.Fatalf("解析状态响应失败:%v", err)
}
if payload.Version != buildinfo.Version || payload.ConfigVersion != config.CurrentVersion {
t.Fatalf("状态版本字段不正确:%+v", payload)
}
}
func TestDomainAPIValidatesSANAndHidesInternalErrors(t *testing.T) {
cfg := config.Default(t.TempDir())
repo := &stubDomainRepository{}
server := New(Dependencies{Config: cfg, Repository: repo})
invalid := httptest.NewRequest(http.MethodPost, "/api/v1/domains", strings.NewReader(`{"name":"example.com","certificate_type":"san","sans":["bad_domain"]}`))
invalid.Header.Set("Content-Type", "application/json")
invalidResponse := httptest.NewRecorder()
server.Handler().ServeHTTP(invalidResponse, invalid)
if invalidResponse.Code != http.StatusBadRequest || strings.Contains(invalidResponse.Body.String(), "detail") {
t.Fatalf("非法 SAN 响应不正确:%d %s", invalidResponse.Code, invalidResponse.Body.String())
}
valid := httptest.NewRequest(http.MethodPost, "/api/v1/domains", strings.NewReader(`{"name":"example.com","certificate_type":"san","sans":["www.example.com"]}`))
valid.Header.Set("Content-Type", "application/json")
validResponse := httptest.NewRecorder()
server.Handler().ServeHTTP(validResponse, valid)
if validResponse.Code != http.StatusCreated || len(repo.created.SANs) != 2 || repo.created.SANs[0] != "example.com" {
t.Fatalf("合法 SAN 响应不正确:%d %s", validResponse.Code, validResponse.Body.String())
}
repo.listErr = errors.New("internal-dsn-secret")
listResponse := httptest.NewRecorder()
server.Handler().ServeHTTP(listResponse, httptest.NewRequest(http.MethodGet, "/api/v1/domains", nil))
if listResponse.Code != http.StatusInternalServerError {
t.Fatalf("列表错误状态码不正确:%d", listResponse.Code)
}
if strings.Contains(listResponse.Body.String(), "internal-dsn-secret") || strings.Contains(listResponse.Body.String(), "detail") {
t.Fatalf("接口泄露了底层错误:%s", listResponse.Body.String())
}
}
func TestDeleteMissingDomainReturnsNotFound(t *testing.T) {
cfg := config.Default(t.TempDir())
repo := &stubDomainRepository{deleteErr: sql.ErrNoRows}
server := New(Dependencies{Config: cfg, Repository: repo})
response := httptest.NewRecorder()
server.Handler().ServeHTTP(response, httptest.NewRequest(http.MethodDelete, "/api/v1/domains/missing", nil))
if response.Code != http.StatusNotFound || strings.Contains(response.Body.String(), "detail") {
t.Fatalf("删除不存在域名响应不正确:%d %s", response.Code, response.Body.String())
}
}
+146
View File
@@ -0,0 +1,146 @@
package httpapi
import (
"context"
"errors"
"net"
"net/http"
"strconv"
"time"
"github.com/gin-gonic/gin"
"git.pcux.cn/xuans/Scert/backend/internal/buildinfo"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
"git.pcux.cn/xuans/Scert/backend/internal/logging"
"git.pcux.cn/xuans/Scert/backend/internal/repository"
)
type Dependencies struct {
Config config.Config
Logger *logging.Logger
Repository repository.DomainRepository
}
type Server struct {
config config.Config
logger *logging.Logger
repository repository.DomainRepository
httpServer *http.Server
router *gin.Engine
}
func New(deps Dependencies) *Server {
gin.SetMode(gin.ReleaseMode)
router := gin.New()
router.Use(gin.Recovery())
server := &Server{config: deps.Config, logger: deps.Logger, repository: deps.Repository, router: router}
server.registerRoutes()
return server
}
func (s *Server) registerRoutes() {
s.router.GET("/healthz", s.health)
s.router.GET("/api/v1/status", s.status)
s.router.GET("/api/v1/domains", s.listDomains)
s.router.POST("/api/v1/domains", s.createDomain)
s.router.DELETE("/api/v1/domains/:id", s.deleteDomain)
}
func (s *Server) Handler() http.Handler {
return s.router
}
func (s *Server) ListenAndServe() error {
s.httpServer = &http.Server{
Addr: net.JoinHostPort(s.config.Server.Host, strconv.Itoa(s.config.Server.Port)),
Handler: s.router,
ReadHeaderTimeout: 10 * time.Second,
ReadTimeout: 30 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 60 * time.Second,
}
if s.logger != nil {
s.logger.Info("HTTP 服务启动", "address", s.httpServer.Addr, "https_mode", s.config.Server.HTTPSMode)
}
return s.httpServer.ListenAndServe()
}
func (s *Server) Shutdown(ctx context.Context) error {
if s.httpServer == nil {
return nil
}
err := s.httpServer.Shutdown(ctx)
if errors.Is(err, http.ErrServerClosed) {
return nil
}
return err
}
type createDomainRequest struct {
Name string `json:"name" binding:"required"`
CertificateType string `json:"certificate_type" binding:"required"`
SANs []string `json:"sans"`
}
func (s *Server) health(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"status": "ok", "service": "scert"})
}
func (s *Server) status(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{
"service": "scert",
"version": buildinfo.Version,
"config_version": s.config.Version,
"setup_ready": s.config.SetupReady,
"https_mode": s.config.Server.HTTPSMode,
"database_driver": s.config.Database.Driver,
})
}
func (s *Server) listDomains(c *gin.Context) {
items, err := s.repository.List(c.Request.Context())
if err != nil {
s.writeError(c, http.StatusInternalServerError, "查询域名失败", err)
return
}
c.JSON(http.StatusOK, gin.H{"items": items})
}
func (s *Server) createDomain(c *gin.Context) {
var request createDomainRequest
if err := c.ShouldBindJSON(&request); err != nil {
s.writeError(c, http.StatusBadRequest, "请求参数无效", err)
return
}
item, err := domain.NewDomain(request.Name, domain.CertificateType(request.CertificateType), request.SANs)
if err != nil {
s.writeError(c, http.StatusBadRequest, "域名配置无效", err)
return
}
if err := s.repository.Create(c.Request.Context(), item); err != nil {
s.writeError(c, http.StatusInternalServerError, "保存域名失败", err)
return
}
c.JSON(http.StatusCreated, item)
}
func (s *Server) deleteDomain(c *gin.Context) {
if err := s.repository.Delete(c.Request.Context(), c.Param("id")); err != nil {
if repository.IsNotFound(err) {
s.writeError(c, http.StatusNotFound, "域名不存在", err)
return
}
s.writeError(c, http.StatusInternalServerError, "删除域名失败", err)
return
}
c.Status(http.StatusNoContent)
}
func (s *Server) writeError(c *gin.Context, status int, message string, err error) {
if s.logger != nil {
s.logger.Error(message, "error", err)
}
c.JSON(status, gin.H{"error": message})
}
+55
View File
@@ -0,0 +1,55 @@
package httpapi
import (
"context"
"net/http"
"net/http/httptest"
"path/filepath"
"strings"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/database"
"git.pcux.cn/xuans/Scert/backend/internal/logging"
"git.pcux.cn/xuans/Scert/backend/internal/repository"
)
func TestHealthAndDomainAPI(t *testing.T) {
dir := t.TempDir()
cfg := config.Default(dir)
cfg.Database.DSN = filepath.Join(dir, "data", "test.db")
db, err := database.Open(context.Background(), cfg.Database)
if err != nil {
t.Fatalf("打开数据库失败:%v", err)
}
defer db.Close()
if err := database.Migrate(context.Background(), db.DB, "sqlite"); err != nil {
t.Fatalf("数据库迁移失败:%v", err)
}
logger, err := logging.New(filepath.Join(dir, "logs"), 0)
if err != nil {
t.Fatalf("初始化日志失败:%v", err)
}
defer logger.Close()
server := New(Dependencies{Config: cfg, Logger: logger, Repository: repository.NewSQLDomainRepository(db.DB)})
health := httptest.NewRecorder()
server.Handler().ServeHTTP(health, httptest.NewRequest(http.MethodGet, "/healthz", nil))
if health.Code != http.StatusOK || !strings.Contains(health.Body.String(), `"status":"ok"`) {
t.Fatalf("健康检查响应错误:%d %s", health.Code, health.Body.String())
}
request := httptest.NewRequest(http.MethodPost, "/api/v1/domains", strings.NewReader(`{"name":"example.com","certificate_type":"single"}`))
request.Header.Set("Content-Type", "application/json")
created := httptest.NewRecorder()
server.Handler().ServeHTTP(created, request)
if created.Code != http.StatusCreated {
t.Fatalf("创建域名响应错误:%d %s", created.Code, created.Body.String())
}
list := httptest.NewRecorder()
server.Handler().ServeHTTP(list, httptest.NewRequest(http.MethodGet, "/api/v1/domains", nil))
if list.Code != http.StatusOK || !strings.Contains(list.Body.String(), "example.com") {
t.Fatalf("域名列表响应错误:%d %s", list.Code, list.Body.String())
}
}
+38
View File
@@ -0,0 +1,38 @@
package logging
import (
"io"
"log/slog"
"os"
"path/filepath"
)
type Logger struct {
*slog.Logger
file *os.File
}
func New(logDir string, level slog.Level) (*Logger, error) {
if err := os.MkdirAll(logDir, 0o750); err != nil {
return nil, err
}
path := filepath.Join(logDir, "scert.log")
file, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
if err != nil {
return nil, err
}
if err := file.Chmod(0o600); err != nil {
_ = file.Close()
return nil, err
}
writer := io.MultiWriter(os.Stdout, file)
handler := slog.NewJSONHandler(writer, &slog.HandlerOptions{Level: level})
return &Logger{Logger: slog.New(handler), file: file}, nil
}
func (l *Logger) Close() error {
if l == nil || l.file == nil {
return nil
}
return l.file.Close()
}
+40
View File
@@ -0,0 +1,40 @@
package logging
import (
"log/slog"
"os"
"path/filepath"
"runtime"
"strings"
"testing"
)
func TestLoggerWritesJSONAndUsesRestrictedPermissions(t *testing.T) {
dir := t.TempDir()
logger, err := New(dir, slog.LevelInfo)
if err != nil {
t.Fatalf("初始化日志失败:%v", err)
}
logger.Info("复审日志", "component", "test")
if err := logger.Close(); err != nil {
t.Fatalf("关闭日志失败:%v", err)
}
path := filepath.Join(dir, "scert.log")
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("读取日志失败:%v", err)
}
text := string(data)
if !strings.Contains(text, `"msg":"复审日志"`) || !strings.Contains(text, `"component":"test"`) {
t.Fatalf("日志内容不正确:%s", text)
}
if runtime.GOOS != "windows" {
info, err := os.Stat(path)
if err != nil {
t.Fatalf("读取日志权限失败:%v", err)
}
if info.Mode().Perm() != 0o600 {
t.Fatalf("日志文件权限不正确:%o", info.Mode().Perm())
}
}
}
@@ -0,0 +1,14 @@
package repository
import (
"context"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
)
type DomainRepository interface {
Create(ctx context.Context, item domain.Domain) error
GetByID(ctx context.Context, id string) (domain.Domain, error)
List(ctx context.Context) ([]domain.Domain, error)
Delete(ctx context.Context, id string) error
}
@@ -0,0 +1,126 @@
package repository
import (
"context"
"database/sql"
"encoding/json"
"errors"
"fmt"
"time"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
)
type SQLDomainRepository struct {
db *sql.DB
}
func NewSQLDomainRepository(db *sql.DB) *SQLDomainRepository {
return &SQLDomainRepository{db: db}
}
func (r *SQLDomainRepository) Create(ctx context.Context, item domain.Domain) error {
if r == nil || r.db == nil {
return errors.New("数据库连接不能为空")
}
payload, err := json.Marshal(item.SANs)
if err != nil {
return fmt.Errorf("编码 SAN 域名失败:%w", err)
}
_, err = r.db.ExecContext(ctx, `INSERT INTO domains
(id, name, certificate_type, sans_json, status, expires_at, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, item.ID, item.Name, item.CertificateType, string(payload), item.Status,
nullableTime(item.ExpiresAt), item.CreatedAt, item.UpdatedAt)
if err != nil {
return fmt.Errorf("保存域名失败:%w", err)
}
return nil
}
func (r *SQLDomainRepository) GetByID(ctx context.Context, id string) (domain.Domain, error) {
if r == nil || r.db == nil {
return domain.Domain{}, errors.New("数据库连接不能为空")
}
row := r.db.QueryRowContext(ctx, `SELECT id, name, certificate_type, sans_json, status, expires_at, created_at, updated_at
FROM domains WHERE id = ?`, id)
return scanDomain(row)
}
func (r *SQLDomainRepository) List(ctx context.Context) ([]domain.Domain, error) {
if r == nil || r.db == nil {
return nil, errors.New("数据库连接不能为空")
}
rows, err := r.db.QueryContext(ctx, `SELECT id, name, certificate_type, sans_json, status, expires_at, created_at, updated_at
FROM domains ORDER BY name`)
if err != nil {
return nil, fmt.Errorf("查询域名失败:%w", err)
}
defer rows.Close()
items := make([]domain.Domain, 0)
for rows.Next() {
item, err := scanDomain(rows)
if err != nil {
return nil, err
}
items = append(items, item)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("读取域名结果失败:%w", err)
}
return items, nil
}
func (r *SQLDomainRepository) Delete(ctx context.Context, id string) error {
if r == nil || r.db == nil {
return errors.New("数据库连接不能为空")
}
result, err := r.db.ExecContext(ctx, "DELETE FROM domains WHERE id = ?", id)
if err != nil {
return fmt.Errorf("删除域名失败:%w", err)
}
count, err := result.RowsAffected()
if err != nil {
return fmt.Errorf("读取删除结果失败:%w", err)
}
if count == 0 {
return sql.ErrNoRows
}
return nil
}
type scanner interface {
Scan(dest ...any) error
}
func scanDomain(row scanner) (domain.Domain, error) {
var item domain.Domain
var certificateType string
var sansJSON string
var expiresAt sql.NullTime
if err := row.Scan(&item.ID, &item.Name, &certificateType, &sansJSON, &item.Status, &expiresAt, &item.CreatedAt, &item.UpdatedAt); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return domain.Domain{}, sql.ErrNoRows
}
return domain.Domain{}, fmt.Errorf("读取域名失败:%w", err)
}
if err := json.Unmarshal([]byte(sansJSON), &item.SANs); err != nil {
return domain.Domain{}, fmt.Errorf("解析 SAN 域名失败:%w", err)
}
item.CertificateType = domain.CertificateType(certificateType)
if expiresAt.Valid {
value := expiresAt.Time
item.ExpiresAt = &value
}
return item, nil
}
func nullableTime(value *time.Time) any {
if value == nil {
return nil
}
return value.UTC()
}
func IsNotFound(err error) bool {
return err != nil && errors.Is(err, sql.ErrNoRows)
}
@@ -0,0 +1,78 @@
package repository
import (
"context"
"database/sql"
"path/filepath"
"testing"
"git.pcux.cn/xuans/Scert/backend/internal/config"
"git.pcux.cn/xuans/Scert/backend/internal/database"
"git.pcux.cn/xuans/Scert/backend/internal/domain"
)
func TestRepositoryRejectsNilDatabase(t *testing.T) {
var repo *SQLDomainRepository
ctx := context.Background()
item, err := domain.NewDomain("example.com", domain.CertificateSingle, nil)
if err != nil {
t.Fatalf("准备域名失败:%v", err)
}
if err := repo.Create(ctx, item); err == nil {
t.Fatal("Create 未拒绝空数据库")
}
if _, err := repo.GetByID(ctx, item.ID); err == nil {
t.Fatal("GetByID 未拒绝空数据库")
}
if _, err := repo.List(ctx); err == nil {
t.Fatal("List 未拒绝空数据库")
}
if err := repo.Delete(ctx, item.ID); err == nil {
t.Fatal("Delete 未拒绝空数据库")
}
if IsNotFound(nil) {
t.Fatal("nil 错误不应被识别为未找到")
}
if !IsNotFound(sql.ErrNoRows) {
t.Fatal("sql.ErrNoRows 未被识别为未找到")
}
}
func TestRepositoryCRUD(t *testing.T) {
dir := t.TempDir()
cfg := config.Default(dir).Database
cfg.DSN = filepath.Join(dir, "data", "repository.db")
db, err := database.Open(context.Background(), cfg)
if err != nil {
t.Fatalf("打开数据库失败:%v", err)
}
defer db.Close()
if err := database.Migrate(context.Background(), db.DB, "sqlite"); err != nil {
t.Fatalf("迁移数据库失败:%v", err)
}
repo := NewSQLDomainRepository(db.DB)
item, err := domain.NewDomain("example.com", domain.CertificateSAN, []string{"www.example.com"})
if err != nil {
t.Fatalf("创建域名模型失败:%v", err)
}
if err := repo.Create(context.Background(), item); err != nil {
t.Fatalf("保存域名失败:%v", err)
}
loaded, err := repo.GetByID(context.Background(), item.ID)
if err != nil {
t.Fatalf("读取域名失败:%v", err)
}
if loaded.Name != item.Name || len(loaded.SANs) != 2 {
t.Fatalf("读取域名内容不正确:%+v", loaded)
}
items, err := repo.List(context.Background())
if err != nil || len(items) != 1 {
t.Fatalf("域名列表不正确:%v,%+v", err, items)
}
if err := repo.Delete(context.Background(), item.ID); err != nil {
t.Fatalf("删除域名失败:%v", err)
}
if err := repo.Delete(context.Background(), item.ID); !IsNotFound(err) {
t.Fatalf("重复删除未返回未找到:%v", err)
}
}
File diff suppressed because it is too large. Load diff
+916
View File
@@ -0,0 +1,916 @@
# SSL 服务程序需求确认文档
- 文档状态:已根据需求确认单更新,73 项用户补充已填写;部分架构事项仍待评审
- 创建日期:2026-08-25
- 适用项目:SSL 证书管理服务程序
- 文档用途:用于确认功能边界、技术方案和验收标准,确认后作为后续设计与开发依据
- 项目名:Scert
> 本文档整理正式需求、待确认事项和开发任务,不代表所有方案已经最终确定。正式需求以已确认结果为准,未确认事项不得擅自假设。
> 填写规则:需求确认阶段,紧跟待确认项后的 `【用户补充 U-编号】` 为用户填写区;需求确认后,系统根据用户补充区同步更新正式需求、流程和验收标准。
---
## 一、需求确认清单
### 1.1 项目目标
- [x] 统一管理多个域名的 SSL/TLS 证书
- [x] 支持自动申请、自动续期和手动部署
- [x] 支持将证书部署到多台远程服务器
- [x] 支持部署完成后的证书校验
- [x] 支持邮件通知和操作日志
- [x] 支持命令行、Web 管理界面和桌面图形界面
- [x] 支持 Windows 和 Linux 运行环境
- [x] 已确认需求:第一阶段同时提供命令行、Web 管理界面和桌面图形界面;命令行仅负责初始化基础配置,初始化完成后日常管理通过 Web 界面进行。
- 【用户补充 U-001】(请填写):
- 补充内容:命令行系统需要实现,命令行只进行基础信息填写:web页面的域名、dns的配置、ssl证书部署的位置,Web 管理界面需要实现,桌面图形界面需要实现
- 确认结果:已填写
- [x] 已确认需求:第一阶段同时支持 Windows 和 Linux 两条开发线。
- 【用户补充 U-002】(请填写):
- 补充内容:需要,两条线进行开发
- 确认结果:已填写
### 1.2 域名和证书管理
- [x] 支持添加托管域名
- [x] 支持删除托管域名
- [x] 支持配置证书类型
- [x] 支持单域名证书
- [x] 支持泛域名证书
- [x] 证书默认存放在配置根目录下的域名目录中
- [x] 已确认需求:泛域名证书不包含根域名。
- 【用户补充 U-003】(请填写):
- 补充内容:泛域名不需要包含根域名
- 确认结果:已填写
- [x] 已确认需求:证书按生产证书和开发证书分类管理;多域名 SAN 证书纳入第一阶段。
- 【用户补充 U-004】(请填写):
- 补充内容:确认启用
- 确认结果:已填写
- [x] 已确认需求:删除域名时同时删除该域名的历史证书文件。
- 【用户补充 U-005】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:同一域名允许保存多个证书版本;根目录使用 `/ssl/{域名}/`,按生产/开发环境和证书类型分目录,下设泛域名和单域名目录。
- 【用户补充 U-006】(请填写):
- 补充内容:允许,但同一个域名多个版本的证书的话,需要以文件夹区分,文件夹名是证书类型,目录结构为:
/ssl/{域名}/
-*(泛域名)
-{域名}(单域名
目录格式参考这个进行排布设计
- 确认结果:已填写
#### 已确认方向的证书目录结构
```text
/ssl/{域名}/
├── production/ 生产证书
│ ├── wildcard/ 泛域名证书,例如 *.example.com
│ │ ├── current/ 当前使用版本
│ │ └── versions/{版本}/ 历史版本
│ └── single/ 单域名证书,例如 example.com
│ ├── current/
│ └── versions/{版本}/
└── development/ 开发证书,目录结构与 production 相同
```
多域名 SAN 证书纳入第一阶段,证书以主域名作为管理归属,并保存完整的 SAN 域名集合。SAN 证书目录使用证书标识区分不同域名集合:
```text
/ssl/{主域名}/
├── production/
│ ├── wildcard/
│ ├── single/
│ └── san/{证书标识}/
│ ├── current/
│ └── versions/{版本}/
└── development/
├── wildcard/
├── single/
└── san/{证书标识}/
├── current/
└── versions/{版本}/
```
其中 `{证书标识}` 必须能够稳定对应主域名和 SAN 域名集合;域名集合发生变化时创建新的证书版本,不覆盖原有证书版本。
### 1.3 DNS 验证
- [x] 使用 ACME 协议申请证书
- [x] 支持 DNS-01 验证
- [x] 支持 Cloudflare API Token
- [x] 支持阿里云 DNS/RAM 凭据
- [x] 支持 DNSPod API Token
- [x] 预留其他 DNS 服务商适配接口
- [x] 支持 CNAME 委派方式
- [x] 第一阶段 DNS 验证方式支持 Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS,并预留其他服务商适配接口。
- [x] 已确认需求:第一阶段使用 Let's Encrypt 作为 ACME CA,并使用 `go-acme/lego` 负责证书申请、DNS-01 验证和自动续期。
- 【用户补充 U-007】(请填写):
- 补充内容:Let's Encrypt、ZeroSSL、Buypass Go SSL、SSL.com、Google Trust Services
- 确认结果:已填写
- [x] 已确认需求:支持国内外主流 DNS 服务商,并通过适配器扩展。
- 【用户补充 U-008】(请填写):
- 补充内容:需要支持国内外主流dns服务商
- 确认结果:已填写
- [x] 已确认需求:CNAME 委派默认自动创建;自动创建失败时提示用户手动创建。
- 【用户补充 U-009】(请填写):
- 补充内容:无需用户创建,自动创建失败时,提示用户手动创建
- 确认结果:已填写
- [x] 已确认需求:自动检测 DNS Zone 和权限。
- 【用户补充 U-010】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:默认使用一个 API 配置多个域名,并支持后续按域名覆盖配置。
- 【用户补充 U-011】(请填写):
- 补充内容:默认使用一个api配置多个域名
- 确认结果:已填写
- [x] 已确认需求:支持 DNS 传播检测和超时设置。
- 【用户补充 U-012】(请填写):
- 补充内容:需要
- 确认结果:已填写
#### 建议的 DNS 验证抽象
```text
DNS 验证方式
├── DNS API 自动管理
│ ├── Cloudflare
│ ├── 阿里云
│ ├── DNSPod
│ └── 其他适配器
└── CNAME 委派
├── 显示需要创建的 CNAME 记录
├── 检查 CNAME 是否生效
└── 管理委派目标下的 TXT 记录
```
### 1.4 自动续期
- [x] 系统按续期调度策略检查托管证书状态:常规每 3 天检查一次;证书剩余有效期低于 10 天时每天检查一次
- [x] 证书接近到期时自动触发续期
- [x] 续期失败时保留原证书
- [x] 支持手动触发续期
- [x] 支持记录续期任务状态
- [x] 支持失败重试
- [x] 已确认需求:证书剩余有效期低于 6 天时开启自动续期。
- 【用户补充 U-013】(请填写):
- 补充内容:低于6天时开启自动续期
- 确认结果:已填写
- [x] 已确认需求:剩余有效期低于 6 天时触发续期,剩余有效期低于 3 天时进入紧急重试。
- 【用户补充 U-014】(请填写):
- 补充内容:默认提前 6 天尝试,剩余 3 天进入紧急重试
- 确认结果:已填写
- [x] 已确认需求:每 3 天检查一次;有效期低于 10 天时每天检查一次。
- 【用户补充 U-015】(请填写):
- 补充内容:每3天检查一次,有效期低于10天时,每天检查一次
- 确认结果:已填写
- [x] 已确认需求:允许用户自定义续期时间和重试次数;默认重试 3 次,每次间隔 30 分钟,并发送邮件提醒。
- 【用户补充 U-016】(请填写):
- 补充内容:允许用户自定义续期时间和重试次数,默认重试3次,每次间隔30分钟,同时发送邮件提醒
- 确认结果:已填写
- [x] 已确认需求:提供 ACME Staging 测试环境。
- 【用户补充 U-017】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:申请任务串行执行,同时只运行一个申请任务;多个任务按提交顺序执行。
- 【用户补充 U-018】(请填写):
- 补充内容:需要,每次限制一个申请任务,用户提交多个任务时,按提交的顺序进行申请,避免申请失败出现
- 确认结果:已填写
#### 已确认的续期配置
```text
常规检查间隔:每 3 天
临近到期检查:剩余有效期低于 10 天时每天检查
自动续期阈值:剩余有效期低于 6 天
紧急重试阈值:剩余有效期低于 3 天
默认最大重试次数:3 次
默认重试间隔:30 分钟
自定义配置:用户可以自定义续期时间和重试次数
```
### 1.5 多服务器部署
- [x] 一个域名可以关联多台服务器
- [x] 使用 SSH 密钥认证
- [x] 不使用服务器登录密码
- [x] 支持上传证书和私钥
- [x] 支持替换远程证书文件
- [x] 支持执行 Web 服务器或反向代理配置检查;默认适配 Nginx
- [x] 支持执行默认或用户自定义的 reload 命令
- [x] 支持部署完成后的远程 HTTPS 检查
- [x] 支持保留旧证书
- [x] 已确认需求:默认使用 Nginx;检测到其他 Web 服务器或反向代理时提示用户修改,并适配主流软件。
- 【用户补充 U-019】(请填写):
- 补充内容:默认使用Nginx,如果用户使用其他的,提示用户进行修改,同时适配当前主流的web服务器/反向代理软件
- 确认结果:已填写
- [x] 已确认需求:支持自定义 reload 命令。
- 【用户补充 U-020】(请填写):
- 补充内容:支持自定义
- 确认结果:已填写
- [x] 已确认需求:每台服务器允许单独配置证书路径,未配置时使用默认路径。
- 【用户补充 U-021】(请填写):
- 补充内容:允许单独配置,不配置就使用默认的路径
- 确认结果:已填写
- [x] 已确认需求:每台服务器允许单独配置 SSH 用户、端口和密钥。
- 【用户补充 U-022】(请填写):
- 补充内容:允许
- 确认结果:已填写
- [x] 已确认需求:记录 SSH 主机指纹。
- 【用户补充 U-023】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:部署任务重试 3 次仍失败后,报告当前状态并通过邮件发送任务摘要。
- 【用户补充 U-024】(请填写):
- 补充内容:重试3次仍然失败后,将当前状态报告给用户,整理任务状态发送给用户使用邮件
- 确认结果:已填写
- [x] 已确认需求:部署失败时自动回滚,避免影响生产环境。
- 【用户补充 U-025】(请填写):
- 补充内容:需要,避免影响生产环境
- 确认结果:已填写
#### 建议的部署流程
```text
1. 本地校验证书和私钥
2. 生成部署版本目录
3. 推送到远程目录
4. 设置远程文件权限
5. 执行 nginx -t
6. 原子替换证书文件
7. 执行 nginx -s reload
8. 发起远程 HTTPS 校验
9. 校验失败时恢复旧版本
10. 记录每台服务器的结果
```
### 1.6 部署后校验
- [x] 校验本地证书文件存在
- [x] 校验证书格式有效
- [x] 校验证书和私钥匹配
- [x] 校验证书未过期
- [x] 校验证书域名匹配
- [x] 校验远程服务器实际返回的证书
- [x] 校验证书链和 TLS 握手
- [x] 已确认需求:部署后检查域名的所有 A 记录。
- 【用户补充 U-026】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:部署后检查 AAAA 记录。
- 【用户补充 U-027】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:远程 HTTPS 校验超时时间为 2 分钟。
- 【用户补充 U-028】(请填写):
- 补充内容:2分钟
- 确认结果:已填写
- [x] 已确认需求:生产证书不允许使用自签名临时证书,测试证书允许使用。
- 【用户补充 U-029】(请填写):
- 补充内容:生产证书不允许,测试证书允许
- 确认结果:已填写
### 1.7 用户自有证书
- [x] 支持上传已有证书
- [x] 支持上传私钥
- [x] 支持手动触发部署
- [x] 上传证书前进行格式检查
- [x] 检查证书和私钥是否匹配
- [x] 检查证书域名和有效期
- [x] 已确认需求:允许上传加密私钥。
- 【用户补充 U-030】(请填写):
- 补充内容:允许
- 确认结果:已填写
- [x] 已确认需求:用户上传证书保留最新版本和一个最近的历史版本。
- 【用户补充 U-031】(请填写):
- 补充内容:保留最新的版本与一个最近的历史版本
- 确认结果:已填写
- [x] 已确认需求:用户上传证书默认不参与自动续期,用户主动选择后才参与。
- 【用户补充 U-032】(请填写):
- 补充内容:默认不参与,除非用户选择参与
- 确认结果:已填写
- [x] 已确认需求:证书文件最大 5 MB,压缩包最大 10 MB。
- 【用户补充 U-033】(请填写):
- 补充内容:证书文件限制最大5mb,压缩包10mb
- 确认结果:已填写
### 1.8 邮件通知
- [x] 每次续期任务完成后发送通知
- [x] 任务成功时发送通知
- [x] 任务失败时发送通知
- [x] 支持多个收件人
- [x] 通知内容包含域名、任务状态、错误信息和时间
- [x] 已确认需求:同时保留 HTTP API 和 SMTP 通知方式;HTTP 通知通过调用外部邮件或消息服务 API 完成,Scert 不实现 SMTP、IMAP、POP3 邮件服务器端。
- 【用户补充 U-034】(请填写):
- 补充内容:http和smtp都保留,后期经过测试后决定保留具体方式
- 确认结果:已填写
#### HTTP 通知接口已确认模板
```text
请求方法:POST
请求地址:用户可自定义
请求格式:application/json
认证方式:Bearer Token、HMAC-SHA256、无认证均支持;无认证仅建议用于开发、测试或受控内网环境
请求头:支持 Scert 标准请求头和用户自定义请求头
事件模式:详细事件和统一事件均支持,默认使用详细事件
成功判定:HTTP 状态码 200-299
请求唯一标识:必须携带 request_id,接收方需要支持幂等处理
超时时间:默认 10 秒,可配置
失败重试:默认 3 次,间隔 30 秒、2 分钟、10 分钟,可配置
敏感信息:Token、签名密钥和密码不得写入日志
```
请求体至少包含:事件类型、任务状态、任务编号、域名、证书类型、运行环境、开始时间、结束时间、错误信息、重试信息和部署结果。用户可选择是否发送完整服务器部署明细、证书序列号和管理后台链接;上述内容默认支持配置。
HTTP 通知接口确认项:
- [x] 请求路径允许用户自定义。
- [x] 支持 Bearer Token。
- [x] 支持 HMAC-SHA256。
- [x] 保留无认证模式;该模式仅建议用于开发、测试或受控内网环境。
- [x] 同时支持详细事件和统一事件,默认使用详细事件。
- [x] 支持发送完整服务器部署明细。
- [x] 支持发送证书序列号。
- [x] 支持发送管理后台链接。
- [x] HTTP 状态码按 200-299 判定为成功。
- [x] 重试次数和间隔支持使用默认值,也支持用户自定义。
- [x] 请求字段统一使用英文。
- [x] 支持用户自定义请求头。
建议请求头:
```text
Content-Type: application/json
Authorization: Bearer {token}
X-Scert-Event: certificate.renewed
X-Scert-Request-Id: {request_id}
X-Scert-Timestamp: {unix_timestamp}
X-Scert-Signature: sha256={hmac_signature}
```
- [x] 已确认需求:SMTP、IMAP、POP3 和 Web 管理后台的协议连接表仅作为外部邮件服务兼容性参考,不作为 Scert 实现邮件服务器端的要求;Scert 后续通过外部 API 接口调用邮件发送服务。
- 【用户补充 U-035】(请填写):
- 补充内容:协议表仅作参考,后续通过 API 接口调用外部邮件发送服务。
| 协议 | 明文连接 | STARTTLS/STLS | 隐式 TLS | 端口 |
|---|---|---|---|---|
| SMTP 接收 | 支持 | 支持 | 支持 | 25、465 |
| SMTP Submission | 仅允许建立连接,不允许明文认证 | 支持 | 不在 587 上使用 | 587 |
| IMAP | 不支持 | 不支持 | 支持 | 993 |
| POP3 | 仅允许建立连接,不允许明文认证 | 支持,命令为 `STLS` | 支持 | 110、995 |
| Web 管理后台 | HTTP 初始化期间支持 | 不适用 | HTTPS 支持 | 80、443 |
- 确认结果:已填写
- [x] 已确认需求:发件人显示名称默认为 Scert,发件人地址待测试后确定。
- 【用户补充 U-036】(请填写):
- 补充内容:发件人:Scert,地址等待我测试后决定
- 确认结果:已填写
- [x] 已确认需求:通知发送失败时进行重试。
- 【用户补充 U-037】(请填写):
- 补充内容:需要重试
- 确认结果:已填写
- [x] 已确认需求:支持按域名配置收件人,默认使用账户绑定的邮箱。
- 【用户补充 U-038】(请填写):
- 补充内容:支持,但是默认使用账户绑定的邮箱
- 确认结果:已填写
- [x] 已确认需求:支持通知类型开关。
- 【用户补充 U-039】(请填写):
- 补充内容:支持
- 确认结果:已填写
#### 建议的通知状态
```text
续期结果:成功、失败、错误、未知、根据具体报错进行通知:如dns错误、dns超时等
部署结果:全部成功、部分成功、全部失败、未执行
邮件结果:发送成功、发送失败、未配置
web页面:站内信提示全部的通知状态
```
### 1.9 Web 管理界面
- [x] 管理员登录
- [x] 查看所有托管域名
- [x] 查看证书类型
- [x] 查看证书到期时间
- [x] 查看剩余有效天数
- [x] 查看关联服务器
- [x] 查看最近续期状态
- [x] 添加和删除域名
- [x] 配置 DNS 验证方式
- [x] 配置部署服务器
- [x] 手动续期
- [x] 手动部署
- [x] 上传自有证书
- [x] 修改邮件配置
- [x] 修改证书存储路径
- [x] 查看操作日志
- [x] 已确认需求:管理后台不由核心服务单独终止 HTTPS,前端和后端均需纳入 HTTPS 安全部署;具体终止层待架构评审。
- 【用户补充 U-040】(请填写):
- 补充内容:由你确定边界
- 确认结果:已填写
- [x] 已确认需求:支持多个管理员。
- 【用户补充 U-041】(请填写):
- 补充内容:支持
- 确认结果:已填写
- [x] 已确认需求:支持一个超级管理员、多个管理员和多个普通用户的角色体系。
- 【用户补充 U-042】(请填写):
- 补充内容:需要:1个超级管理员,n个管理员,n个普通用户
- 确认结果:已填写
- [x] 已确认需求:支持用户名加密码、邮箱加密码、邮箱加验证码、用户名加验证码等登录方式。
- 【用户补充 U-043】(请填写):
- 补充内容:需要:通过用户名+密码、邮箱+密码、邮箱+验证码、用户名+验证码
- 确认结果:已填写
- [x] 已确认需求:5 分钟内登录失败 5 次后禁止登录 30 分钟。
- 【用户补充 U-044】(请填写):
- 补充内容:5分钟内失败5次禁止登录30分钟
- 确认结果:已填写
- [x] 已确认需求:连续 30 分钟无操作时自动强制退出。
- 【用户补充 U-045】(请填写):
- 补充内容:30分钟未操作自动强制退出
- 确认结果:已填写
### 1.10 命令行版本
- [x] 初始化配置
- [x] 添加域名
- [x] 删除域名
- [x] 手动续期
- [x] 手动部署
- [x] 查看域名状态
- [x] 查看证书信息
- [x] 查看日志
- [x] 修改系统配置
- [x] 与 Web 管理界面共享配置和数据
- [x] 已确认需求:CLI 通过 API 调用核心服务,不直接操作本地数据库。
- 【用户补充 U-046】(请填写):
- 补充内容:通过api调用服务
- 确认结果:已填写
- [x] 已确认需求:初始化配置时使用交互式输入;初始化完成后不再使用交互式 CLI,转由 Web 页面操作。
- 【用户补充 U-047】(请填写):
- 补充内容:初始化配置时需要交互式输入配置信息,初始化完成后不需要交互式,转由web页面操作
- 确认结果:已填写
- [x] 已确认需求:不支持 JSON 输出。
- 【用户补充 U-048】(请填写):
- 补充内容:不支持
- 确认结果:已填写
- [x] 已确认需求:不支持脚本退出码。
- 【用户补充 U-049】(请填写):
- 补充内容:不支持
- 确认结果:已填写
- [x] 已确认需求:支持任务等待和轮询。
- 【用户补充 U-050】(请填写):
- 补充内容:支持
- 确认结果:已填写
### 1.11 桌面图形界面
- [x] 支持首次初始化
- [x] 支持配置管理员账号
- [x] 支持配置邮件服务器
- [x] 支持配置 DNS 验证
- [x] 支持配置证书存储路径
- [x] 支持打开 Web 管理界面
- [x] 已确认需求:桌面版作为 Web 管理界面的封装。
- 【用户补充 U-051】(请填写):
- 补充内容:是
- 确认结果:已填写
- [x] 已确认需求:桌面版负责启动本地核心服务。
- 【用户补充 U-052】(请填写):
- 补充内容:是
- 确认结果:已填写
- [x] 已确认需求:需要系统托盘。
- 【用户补充 U-053】(请填写):
- 补充内容:是
- 确认结果:已填写
- [x] 已确认需求:需要显示后台任务状态。
- 【用户补充 U-054】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:支持开机自启动,但由用户选择是否启用。
- 【用户补充 U-055】(请填写):
- 补充内容:需要,但是根据用户选择执行
- 确认结果:已填写
- [x] 已确认需求:桌面版安装包格式为 exe。
- 【用户补充 U-056】(请填写):
- 补充内容:exe
- 确认结果:已填写
### 1.12 平台支持
- [x] Windows
- [x] Linux
- [x] Linux systemd 服务
- [x] Windows Service 服务
- [x] 已确认需求:支持 Windows 10 和 Windows 11,目标构建架构为 amd64。
- 【用户补充 U-057】(请填写):
- 补充内容:win10
- 确认结果:已填写
- [x] 已确认需求:第一阶段以 Ubuntu 22.04 + Nginx 作为 Linux 基础测试环境,并覆盖 Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理软件的兼容性测试。
- 【用户补充 U-058】(请填写):
- 补充内容:Ubuntu20.04、debain11
- 确认结果:已填写
- [x] 已确认需求:Linux 服务以 Ubuntu 22.04 的 systemd 版本作为最低 systemd 兼容基线,其他 Linux 发行版通过测试矩阵确认兼容性。
- 【用户补充 U-059】(请填写):
- 补充内容:需要支持到当前最新版
- 确认结果:已填写
- [x] 已确认需求:暂不支持 ARM64。
- 【用户补充 U-060】(请填写):
- 补充内容:暂不需要,没有对应的环境进行测试
- 确认结果:已填写
- [x] 已确认需求:支持主流 Windows、Linux、Web 服务器和反向代理软件。
- 【用户补充 U-061】(请填写):
- 补充内容:主流的win、Linux、web服务器/反向代理都需要支持
- 确认结果:已填写
- [x] 已确认需求:支持在 Windows 上部署 Nginx,并根据用户需求启用。
- 【用户补充 U-062】(请填写):
- 补充内容:支持这个功能,但是根据用户需求启用
- 确认结果:已填写
### 1.13 安全需求
- [x] 管理后台使用 HTTPS
- [x] 管理员密码使用安全哈希保存
- [x] Linux 私钥文件权限限制为 600 或更严格
- [x] Windows 使用等效 ACL 权限保护私钥
- [x] SSH 私钥加密存储
- [x] DNS API 密钥加密存储
- [x] SMTP 密码加密存储
- [x] 日志中禁止记录明文密钥
- [x] 所有重要操作记录审计日志
- [x] 已确认需求:使用主密码保护的加密配置。
- 【用户补充 U-063】(请填写):
- 补充内容:使用主密码保护的加密配置
- 确认结果:已填写
- [x] 已确认需求:需要管理员恢复机制:超级管理员只能通过配套重置入口重置;管理员和普通用户可由超级管理员重置;普通用户可由管理员重置,且普通用户只能重置自身。
- 【用户补充 U-064】(请填写):
- 补充内容:需要:超级管理员只能通过配套的重置入口进行重置,管理员和普通用户可以通过超级管理员重置,普通用户可以通过管理员重置,普通用户只能重置本身
- 确认结果:已填写
- [x] 已确认需求:支持敏感信息轮换。
- 【用户补充 U-065】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:支持加密密钥备份。
- 【用户补充 U-066】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:需要安全审计报告,且仅超级管理员和管理员可以查看。
- 【用户补充 U-067】(请填写):
- 补充内容:需要,但是只能超级管理员和管理员查看
- 确认结果:已填写
### 1.14 可靠性和运维
- [x] 失败时保留原证书
- [x] 续期任务可重试
- [x] 部署任务可重试
- [x] 记录操作日志
- [x] 记录错误原因
- [x] 服务重启后可以恢复任务状态
- [x] 已确认需求:支持数据库备份。
- 【用户补充 U-068】(请填写):
- 补充内容:数据库备份
- 确认结果:已填写
- [x] 已确认需求:日志保留 30 天,默认保留最新 30 天后删除旧日志。
- 【用户补充 U-069】(请填写):
- 补充内容:保留30天,默认保留最新的30天,然后删除旧的
- 确认结果:已填写
- [x] 已确认需求:日志每天限制 5 MB。
- 【用户补充 U-070】(请填写):
- 补充内容:每天限制5mb
- 确认结果:已填写
- [x] 已确认需求:支持日志轮转。
- 【用户补充 U-071】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:支持配置导出和导入。
- 【用户补充 U-072】(请填写):
- 补充内容:需要
- 确认结果:已填写
- [x] 已确认需求:需要灾难恢复流程。
- 【用户补充 U-073】(请填写):
- 补充内容:需要
- 确认结果:已填写
---
## 二、第一阶段范围
以下范围已根据需求确认结果纳入第一阶段。具体实现仍需按照开发任务清单逐项完成并复审。
- [x] 已确认纳入:核心证书管理服务和统一配置、数据模型
- [x] 已确认纳入:数据库存储及任务、日志、证书版本数据管理
- [x] 已确认纳入:Let’s Encrypt ACME CA,并使用 `go-acme/lego` 负责证书申请、DNS-01 验证和自动续期
- [x] 已确认纳入:Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS 及其他服务商适配器
- [x] 已确认纳入:DNS-01 验证、DNS Zone 和权限检测、DNS 传播检测
- [x] 已确认纳入:CNAME 委派自动创建;自动创建失败时提示用户手动创建
- [x] 已确认纳入:单域名证书、泛域名证书(不包含根域名)、多域名 SAN 证书以及生产/开发证书分类
- [x] 已确认纳入:证书多版本保存、按证书类型分目录、失败时保留原证书
- [x] 已确认纳入:通过 SSH 密钥部署到多台服务器,支持独立配置路径、用户、端口和密钥
- [x] 已确认纳入:默认 Nginx,适配主流 Web 服务器和反向代理,并支持自定义 reload 命令
- [x] 已确认纳入:部署失败重试、自动回滚、A/AAAA 记录检查和远程 HTTPS 校验
- [x] 已确认纳入:HTTP API 和 SMTP 通知方式;SMTP、IMAP、POP3 协议表仅作为外部邮件服务兼容性参考,Scert 不实现邮件服务器端
- [x] 已确认纳入:MySQL 5.7 基础开发、MySQL 8.0 兼容性测试和 SQLite 单机/桌面/开发模式
- [x] 已确认纳入:Linux 默认目录 `/ssl`、`/scert`、`/scert/conf`、`/scert/log`、`/scert/backups`
- [x] 已确认纳入:Windows 按自定义安装目录使用 `Scert\ssl`、`Scert\data`、`Scert\config`、`Scert\logs`、`Scert\backups`
- [x] 已确认纳入:Linux 创建专用 `Scert` 服务运行用户;该用户专门管理证书目录,私钥由 `Scert` 和 `root` 共同受控管理
- [x] 已确认纳入:CLI 初始化、Web 管理界面和桌面图形界面
- [x] 已确认纳入:多管理员、超级管理员、管理员和普通用户角色权限
- [x] 已确认纳入:Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理测试范围
- [x] 已确认纳入:Linux systemd 服务、Windows Service 服务和桌面版 exe 安装包;systemd 以 Ubuntu 22.04 默认版本为最低兼容基线
- [x] 已确认纳入:以当前开发电脑工具链为开发基线,目标构建架构为 amd64;当前记录为 Go 1.26.2、Node.js 24.19.0、npm 11.17.0、Wails 2.11.0
- [x] 已确认纳入:用户自有证书上传、校验和手动部署;默认不参与自动续期
以下内容暂不纳入第一阶段或仍需后续确认:
- [!] 自定义 ACME CA:第一阶段固定使用 Let’s Encrypt,后续预留扩展
- [!] 高可用、多实例和集群部署
- [!] ARM64 平台支持
- [x] 已确认:HTTPS 采用双模式;默认由核心服务直接终止 HTTPS,高级模式由 Nginx/Caddy 终止公网 HTTPS,核心服务使用内部 HTTPS
---
## 三、建议的系统模块
```text
SSL 服务程序
├── 配置管理模块
├── 管理员认证模块
├── 域名管理模块
├── 证书生命周期模块
├── ACME 客户端模块
├── DNS 服务商适配模块
├── 续期调度模块
├── SSH 部署模块
├── Web 服务器和反向代理适配模块
├── 远程 HTTPS 校验模块
├── 自有证书导入模块
├── 邮件通知模块
├── Web API 模块
├── CLI 模块
├── 桌面客户端模块
├── 审计日志模块
└── 平台服务模块
```
业务逻辑只放在核心服务中,CLI、Web 和桌面客户端不重复实现证书申请及部署逻辑。
---
## 四、建议的证书任务状态
### 4.1 续期任务状态
```text
pending 等待执行
running 执行中
succeeded 成功
failed 失败
partial 部分成功
cancelled 已取消
unknown 未知
```
### 4.2 部署节点状态
```text
pending 等待部署
uploading 上传中
checking 配置检查中
reloading 重载中
validating HTTPS 校验中
succeeded 成功
failed 失败
rolled_back 已回滚
rollback_failed 回滚失败
```
### 4.3 证书来源
```text
acme ACME 自动申请
uploaded 用户上传
imported 外部导入
```
---
## 五、关键业务流程
### 5.1 首次初始化流程
```text
1. 启动程序
2. 检查是否已完成初始化
3. 未初始化时进入初始化向导
4. 配置管理后台域名
5. 配置管理员账号和密码
6. 配置证书存储根目录
7. 配置邮件服务器和通知方式(HTTP、SMTP)
8. 配置至少一种 DNS 验证方式
9. 验证 DNS 凭据、DNS Zone、权限和 DNS 传播能力
10. 检查管理后台域名解析
11. 使用 Let’s Encrypt 和 `go-acme/lego` 通过 DNS-01 申请管理后台证书
12. 校验并安装本地 HTTPS 证书
13. 启动前后端均纳入 HTTPS 部署的管理后台
14. 标记初始化完成
```
### 5.2 自动续期流程
```text
1. 调度器按每 3 天一次的常规周期检查证书;剩余有效期低于 10 天时改为每天检查
2. 证书剩余有效期低于 6 天时创建续期任务;低于 3 天时按紧急策略重试
3. 申请任务进入串行队列,同一时间只运行一个申请任务
4. 检查 DNS 配置、DNS Zone、权限和 ACME 账户
5. 调用 `go-acme/lego` 使用 Let’s Encrypt 创建 ACME Order
6. 创建或委派 DNS TXT 记录
7. 等待并检测 DNS 记录传播
8. 执行 ACME DNS-01 验证并下载新证书
9. 校验新证书和私钥
10. 保存新的本地证书版本
11. 部署到关联服务器并执行 Web 服务器或反向代理检查、reload
12. 检查所有 A/AAAA 记录并执行远程 HTTPS 校验
13. 校验失败或部署失败时恢复旧版本
14. 按默认 3 次、每次间隔 30 分钟的策略重试;用户可自定义续期时间和重试次数
15. 写入任务和审计日志,并发送 HTTP/SMTP 任务通知
```
### 5.3 用户证书部署流程
```text
1. 上传证书和私钥
2. 校验文件格式
3. 校验证书和私钥匹配
4. 校验证书域名和有效期
5. 保存为新版本
6. 用户手动确认部署
7. 部署到关联服务器
8. 执行目标 Web 服务器或反向代理检查和 reload
9. 执行 HTTPS 校验
10. 记录结果并发送通知
```
---
## 六、验收标准
### 6.1 核心功能验收
- [ ] 能通过 CLI 完成首次初始化
- [ ] 能通过 Web 管理界面完成首次初始化
- [ ] 能通过桌面版完成首次初始化,并在初始化后打开 Web 管理界面
- [ ] 能添加单域名
- [ ] 能添加泛域名
- [ ] 能通过 Let’s Encrypt 和 `go-acme/lego` 使用 DNS-01 成功申请证书
- [ ] 能检测 DNS Zone、权限和 DNS 传播状态;CNAME 委派自动创建失败时能提示用户手动创建
- [ ] 能保存证书、证书链和私钥
- [ ] 能按生产证书、开发证书、单域名、泛域名和 SAN 证书保存多个证书版本;泛域名证书不包含根域名,SAN 域名集合变化时创建新的证书版本
- [ ] 能通过 SSH 部署到多台目标服务器,并按服务器独立配置路径、用户、端口和密钥
- [ ] 默认能部署到远程 Nginx,并能适配主流 Web 服务器和反向代理
- [ ] 能执行目标 Web 服务器或反向代理的配置检查和 reload,且支持自定义 reload 命令
- [ ] 能在部署后通过 HTTPS 校验
- [ ] 能按每 3 天检查、低于 10 天每天检查、低于 6 天续期、低于 3 天紧急重试的策略自动续期
- [ ] 默认失败重试 3 次、每次间隔 30 分钟,并允许用户自定义续期时间和重试次数
- [ ] 能在失败时保留旧证书
- [ ] 能在部署失败时回滚
- [ ] 能通过 HTTP API 和 SMTP 发送成功、失败、错误、未知等任务通知;HTTP API 支持自定义地址、Bearer Token、HMAC-SHA256、无认证测试模式、详细/统一事件、完整部署明细、证书序列号、管理后台链接、自定义请求头和独立重试
- [ ] 能上传自有证书并手动部署,且默认不参与自动续期
- [ ] 能查看操作日志
### 6.2 安全验收
- [ ] 未登录用户不能访问管理接口
- [ ] 管理员密码不以明文保存
- [ ] DNS 密钥、SMTP 密码和 SSH 私钥不出现在日志中
- [ ] 私钥文件权限符合平台要求
- [ ] 上传路径不能越权
- [ ] 远程 SSH 主机指纹可验证
- [ ] Web 管理后台强制 HTTPS
- [ ] 续期和部署任务不能被未授权用户触发
### 6.3 平台验收
- [ ] Windows 10 及以上环境可以启动核心服务
- [ ] Linux 环境可以启动核心服务
- [ ] Ubuntu 22.04 + Nginx 可以运行
- [ ] Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理通过测试矩阵验证
- [ ] Windows 服务可以自动启动
- [ ] Linux systemd 服务可以自动启动
- [ ] 桌面版可以通过 exe 安装包安装,并能启动本地核心服务、显示系统托盘和后台任务状态
- [ ] Windows 和 Linux 使用同一套业务配置模型
---
## 七、需求确认结果与待确认事项
本节已根据前述用户补充区更新。已确认内容作为正式需求依据,未确认内容不得在实现阶段擅自假设。
### 7.1 已确认的关键结论
1. 第一阶段使用 Let’s Encrypt 作为 ACME CA,并使用 `go-acme/lego` 负责申请、DNS-01 验证和自动续期;其他 ACME CA 仅预留后续扩展能力。
2. 第一阶段支持 Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS 及其他服务商适配器;CNAME 委派自动创建失败时提示用户手动创建。
3. 第一阶段同时保留 HTTP API 和 SMTP 通知方式;SMTP、IMAP、POP3 协议表仅作为外部邮件服务兼容性参考,Scert 通过外部 API 调用邮件发送服务,不实现邮件服务器端。
4. 管理后台采用双 HTTPS 模式:默认由核心服务直接终止 HTTPS;高级模式由 Nginx/Caddy 终止公网 HTTPS,核心服务使用内部 HTTPS。
5. 续期策略为:每 3 天常规检查一次,剩余有效期低于 10 天时每天检查,低于 6 天触发续期,低于 3 天进入紧急重试;默认重试 3 次、每次间隔 30 分钟,用户可自定义续期时间和重试次数。
6. 泛域名证书只申请 `*.example.com` 形式的泛域名,不自动包含 `example.com` 根域名。
7. CNAME 委派默认由程序自动创建;自动创建失败时,必须向用户展示记录并提示手动创建。
8. 第一阶段不限定远程目标为 Linux Nginx;默认支持 Nginx,并适配主流 Windows/Linux Web 服务器和反向代理软件。
9. 桌面版采用 Web 管理界面封装,由桌面版启动本地核心服务,并提供系统托盘、后台任务状态和可选开机自启动。
10. 协议连接表仅作为外部邮件服务兼容性参考;通知接口支持用户自定义地址、Bearer Token、HMAC-SHA256、无认证测试模式、详细/统一事件、自定义请求头、2xx 成功判定和可配置重试。
11. 多域名 SAN 证书纳入第一阶段,使用主域名作为管理归属并保存完整 SAN 域名集合;域名集合变化时生成新的证书版本。
12. 数据库支持 MySQL 和 SQLite;MySQL 5.7 作为基础开发和最低兼容版本,MySQL 8.0 作为兼容性测试版本,SQLite 用于单机、桌面和开发模式。
13. Linux 默认使用 `/ssl`、`/scert`、`/scert/conf`、`/scert/log`、`/scert/backups`;创建专用 `Scert` 服务运行用户管理证书目录,私钥由 `Scert` 和 `root` 共同受控管理。Windows 按自定义安装目录使用 `Scert\\ssl`、`Scert\\data`、`Scert\\config`、`Scert\\logs`、`Scert\\backups`。
### 7.2 仍需确认或架构评审的事项
- [x] 已确认:U-004 多域名 SAN 证书纳入第一阶段,目录、申请、续期和部署规则已纳入正式需求。
- [x] 已确认:U-040 HTTPS 采用双模式,默认核心服务直接终止,高级模式由 Nginx/Caddy 终止公网 HTTPS,核心服务使用内部 HTTPS。
- [x] 已确认:平台测试范围为 Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理。
---
## 八、需求确认后的开发任务清单
### 阶段一:基础设计
- [ ] 未开始:冻结第一阶段需求范围
- [ ] 未开始:确定核心服务和数据模型
- [ ] 未开始:确定配置文件和数据库方案
- [ ] 未开始:确定敏感信息加密方案
- [ ] 未开始:确定证书目录和版本结构
- [ ] 未开始:确定任务状态机
- [ ] 未开始:确定 Windows、Linux、Windows Service 和 Linux systemd 的运行适配边界
- [ ] 未开始:建立 Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理测试矩阵
### 阶段二:证书申请
- [ ] 未开始:实现 `go-acme/lego` ACME Issuer 和生命周期管理
- [ ] 未开始:接入 Let’s Encrypt 生产环境和 ACME Staging 测试环境
- [ ] 未开始:实现 DNS 服务商适配器接口
- [ ] 未开始:实现国内外主流 DNS 服务商适配器
- [ ] 未开始:实现 CNAME 委派自动创建、失败提示和传播检测
- [ ] 未开始:实现 DNS Zone、权限和 DNS 传播检测
- [ ] 未开始:实现证书保存和校验
- [ ] 未开始:实现生产/开发证书分类及单域名、泛域名证书目录
- [ ] 未开始:实现多域名 SAN 证书标识集合、目录、申请、续期、版本保存和部署关联
### 阶段三:续期和部署
- [ ] 未开始:实现每 3 天检查、低于 10 天每天检查的调度器
- [ ] 未开始:实现低于 6 天续期、低于 3 天紧急重试的续期任务
- [ ] 未开始:实现申请任务串行队列和任务等待、轮询
- [ ] 未开始:实现默认 3 次、每次间隔 30 分钟且可配置的失败重试
- [ ] 未开始:实现 SSH 部署
- [ ] 未开始:实现 Web 服务器和反向代理部署适配器,默认支持 Nginx
- [ ] 未开始:实现远程配置检查、默认或自定义 reload 命令
- [ ] 未开始:实现远程 HTTPS 校验
- [ ] 未开始:实现版本化部署和回滚
- [ ] 未开始:实现所有 A/AAAA 记录检查
- [ ] 未开始:实现 HTTP API 和 SMTP 任务通知及通知失败重试
### 阶段四:管理界面
- [ ] 未开始:实现管理员认证
- [ ] 未开始:实现超级管理员、管理员和普通用户角色权限
- [ ] 未开始:实现 Web API
- [ ] 未开始:实现域名管理页面
- [ ] 未开始:实现证书状态页面
- [ ] 未开始:实现服务器配置页面
- [ ] 未开始:实现任务和日志页面
- [ ] 未开始:实现初始化向导
### 阶段五:平台和扩展
- [ ] 未开始:实现 Linux systemd 适配
- [ ] 未开始:实现 Windows Service 适配
- [ ] 未开始:实现桌面版 Web 封装、核心服务启动、系统托盘和后台任务状态
- [ ] 未开始:实现桌面版 exe 安装包和可选开机自启动
- [ ] 未开始:实现用户证书上传
- [ ] 未开始:实现数据库备份、配置导入导出和灾难恢复
- [ ] 未开始:实现敏感信息轮换、加密密钥备份和安全审计报告
- [ ] 未开始:实现外部邮件服务 API 通知、SMTP 通知和 HTTP 通知配置页面
- [ ] 未开始:实现双 HTTPS 模式、Linux systemd 最低基线和 Windows Service 适配
- [ ] 未开始:预留自定义 ACME CA、高可用、多实例和 ARM64 扩展
---
## 九、确认记录
| 日期 | 确认人 | 变更内容 | 结果 |
|---|---|---|---|
| 2026-08-25 | 用户与系统整理 | 根据用户补充 U-035 更新协议连接策略、端口和认证限制 | 73 项已填写 |
---
## 十、文档状态说明
- `[ ]` 未开始
- `[~]` 进行中
- `[x]` 已完成,等待复审
- `[✓]` 复审通过
- `[!]` 暂缓或存在阻塞
需求确认后,已填写并整理的条目标记为 `[x]`,等待复审;复审通过后标记为 `[✓]`;暂缓、阻塞或仍需确认的条目标记为 `[!]`。开发任务清单中的任务在实际开发过程中按状态更新。
File diff suppressed because it is too large. Load diff
+12
View File
@@ -0,0 +1,12 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Scert SSL 证书管理</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.js"></script>
</body>
</html>
+1382
View File
File diff suppressed because it is too large. Load diff
+18
View File
@@ -0,0 +1,18 @@
{
"name": "scert-frontend",
"private": true,
"version": "0.1.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
},
"dependencies": {
"vue": "^3.5.0"
},
"devDependencies": {
"@vitejs/plugin-vue": "^5.2.0",
"vite": "^6.0.0"
}
}
+79
View File
@@ -0,0 +1,79 @@
<script setup>
import { onMounted, ref } from 'vue'
const status = ref(null)
const domains = ref([])
const loading = ref(true)
const error = ref('')
const certificateTypeLabels = { single: '单域名', wildcard: '泛域名', san: 'SAN 多域名' }
const domainStatusLabels = { pending: '等待处理', active: '正常', error: '错误' }
const httpsModeLabels = { direct: '核心服务 HTTPS', proxy: '反向代理 HTTPS' }
function displayLabel(labels, value) {
return labels[value] || (value ? '未知' : '—')
}
async function loadData() {
loading.value = true
error.value = ''
try {
const [statusResponse, domainResponse] = await Promise.all([
fetch('/api/v1/status'),
fetch('/api/v1/domains'),
])
if (!statusResponse.ok || !domainResponse.ok) throw new Error('服务接口返回失败')
status.value = await statusResponse.json()
domains.value = (await domainResponse.json()).items || []
} catch {
error.value = '无法连接核心服务'
} finally {
loading.value = false
}
}
onMounted(loadData)
</script>
<template>
<main class="page-shell">
<header class="topbar">
<div>
<p class="eyebrow">SCERT / SSL 证书管理</p>
<h1>证书管理总览</h1>
</div>
<button class="secondary-button" type="button" @click="loadData">刷新状态</button>
</header>
<section class="hero-card">
<div>
<span class="status-dot" :class="{ online: status }"></span>
<span class="status-label">{{ status ? '核心服务运行中' : '等待连接核心服务' }}</span>
<h2>让证书续期和部署变得可追踪</h2>
<p>首轮界面展示服务状态和托管域名,后续将接入 ACME、DNS 验证与远程部署流程。</p>
</div>
<div class="hero-mark">S</div>
</section>
<p v-if="error" class="error-banner">{{ error }}。请先执行 <code>scert serve</code>。</p>
<section class="metrics-grid">
<article class="metric-card"><span>服务版本</span><strong>{{ status?.version || '—' }}</strong></article>
<article class="metric-card"><span>数据库</span><strong>{{ displayLabel({ sqlite: 'SQLite', mysql: 'MySQL' }, status?.database_driver) || '—' }}</strong></article>
<article class="metric-card"><span>HTTPS 模式</span><strong>{{ displayLabel(httpsModeLabels, status?.https_mode) || '—' }}</strong></article>
<article class="metric-card"><span>托管域名</span><strong>{{ domains.length }}</strong></article>
</section>
<section class="panel">
<div class="panel-heading"><div><p class="eyebrow">域名列表</p><h2>托管域名</h2></div><span class="muted">首轮占位视图</span></div>
<div v-if="loading" class="empty-state">正在读取域名状态……</div>
<div v-else-if="domains.length === 0" class="empty-state">暂未添加托管域名,请通过 CLI 执行 <code>scert domain add</code>。</div>
<div v-else class="domain-list">
<div v-for="item in domains" :key="item.id" class="domain-row">
<div><strong>{{ item.name }}</strong><span>{{ displayLabel(certificateTypeLabels, item.certificate_type) }} · {{ displayLabel(domainStatusLabels, item.status) }}</span></div>
<span class="tag">待处理</span>
</div>
</div>
</section>
</main>
</template>
+5
View File
@@ -0,0 +1,5 @@
import { createApp } from 'vue'
import App from './App.vue'
import './style.css'
createApp(App).mount('#app')
+34
View File
@@ -0,0 +1,34 @@
:root { font-family: Inter, "Microsoft YaHei", sans-serif; color: #172033; background: #f4f7fb; font-synthesis: none; }
* { box-sizing: border-box; }
body { margin: 0; min-width: 320px; }
button { font: inherit; cursor: pointer; }
.page-shell { max-width: 1180px; margin: 0 auto; padding: 42px 28px 70px; }
.topbar, .panel-heading { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.eyebrow { margin: 0 0 9px; color: #687792; font-size: 11px; font-weight: 800; letter-spacing: .15em; }
h1, h2, p { margin-top: 0; }
h1 { margin-bottom: 0; font-size: clamp(30px, 5vw, 52px); letter-spacing: -.05em; }
h2 { margin-bottom: 10px; font-size: clamp(24px, 4vw, 38px); letter-spacing: -.04em; }
.secondary-button { border: 1px solid #d5ddea; border-radius: 12px; background: #fff; color: #32405a; padding: 11px 16px; font-weight: 700; }
.hero-card { display: flex; align-items: center; justify-content: space-between; min-height: 250px; margin: 36px 0 18px; padding: 36px 42px; border-radius: 28px; color: #fff; background: linear-gradient(120deg, #182b5b, #315aaa); box-shadow: 0 20px 45px rgba(42, 75, 145, .2); }
.hero-card p { max-width: 650px; margin-bottom: 0; color: #d5e1ff; line-height: 1.8; }
.status-label { font-size: 13px; font-weight: 800; }
.status-dot { display: inline-block; width: 9px; height: 9px; margin-right: 8px; border-radius: 50%; background: #ffba58; }
.status-dot.online { background: #5ee0a0; box-shadow: 0 0 0 5px rgba(94, 224, 160, .15); }
.hero-mark { display: grid; place-items: center; width: 112px; height: 112px; border: 1px solid rgba(255,255,255,.35); border-radius: 32px; color: #cfe0ff; font-size: 62px; font-weight: 900; }
.error-banner { margin: 18px 0; padding: 14px 18px; border: 1px solid #f0c4c4; border-radius: 12px; color: #9c3b3b; background: #fff2f2; }
.metrics-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; margin-bottom: 18px; }
.metric-card, .panel { border: 1px solid #e2e8f2; border-radius: 20px; background: rgba(255,255,255,.86); box-shadow: 0 10px 30px rgba(31, 50, 87, .04); }
.metric-card { padding: 22px; }
.metric-card span, .domain-row span, .muted { color: #7a879d; font-size: 13px; }
.metric-card strong { display: block; margin-top: 13px; font-size: 28px; }
.panel { padding: 28px; }
.panel-heading { margin-bottom: 22px; }
.panel-heading h2 { margin-bottom: 0; font-size: 26px; }
.empty-state { padding: 36px 10px; color: #7a879d; text-align: center; }
code { padding: 2px 6px; border-radius: 6px; background: #eef2f8; font-family: Consolas, monospace; }
.domain-list { display: grid; gap: 10px; }
.domain-row { display: flex; align-items: center; justify-content: space-between; padding: 15px 16px; border: 1px solid #edf0f5; border-radius: 13px; }
.domain-row strong, .domain-row span { display: block; }
.domain-row strong { margin-bottom: 5px; }
.tag { padding: 5px 10px; border-radius: 99px; background: #fff3d8; color: #9b6a1a !important; font-size: 12px !important; }
@media (max-width: 760px) { .page-shell { padding: 26px 16px 48px; } .hero-card { align-items: flex-start; padding: 28px; } .hero-mark { display: none; } .metrics-grid { grid-template-columns: repeat(2, 1fr); } .panel { padding: 20px; } }
+13
View File
@@ -0,0 +1,13 @@
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
server: {
port: 5173,
proxy: {
'/api': 'http://127.0.0.1:8080',
'/healthz': 'http://127.0.0.1:8080',
},
},
})