Skip to content
ZCT-StudioPublic

About

A "Cloud Verification API" using modern C++ and the Drogon Framework

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ZCT-SLMS

软件授权验证平台后端,提供应用、卡密、账号、工单和内容审查接口。

技术栈

C++ · Drogon · OpenSSL · Argon2id · SQLite / PostgreSQL / MySQL

快速开始

安装 Docker 后,在项目根目录执行:

docker compose up -d --build
docker compose logs -f verifier

默认地址:http://localhost:17112。检查服务:

curl http://localhost:17112/api/v1/ping

首次启动自动生成管理员账号和一次性密码,请从启动日志获取并完成首次设置。WebUI 默认端口为 17316,在前端项目中单独启动。

配置

  • 本机运行默认读取 config/config.yaml,也可通过程序第一个参数指定配置文件。
  • Docker 默认绑定 127.0.0.1:17112;使用 ZCT_SLMS_CORE_BIND_ADDRESS 和 ZCT_SLMS_CORE_PORT 调整宿主机监听地址、端口。
  • 平台设置管理运行配置、SMTP 和邮件模板;安全设置管理注册、第三方登录、2FA、人机验证与权限策略。
  • Microsoft、GitHub、短信、SMTP 等服务需填写自己的凭据。通行密钥需使用 HTTPS 或 localhost。

Docker 使用 zct_slms-config、zct_slms-data、zct_slms-logs 卷保存配置、数据与日志。更新使用 docker compose up -d --build,停止使用 docker compose down。

升级前备份数据库、配置与 data/auth-master.key;三者需配套恢复。docker compose down -v 会删除数据卷,不用于普通停止或升级。

发布平台

二进制发布仅保留 Linux x64、Linux ARM64、Windows x64。macOS、x86、ARMv7 和 Windows ARM64 不再构建或发布。

Windows 发布包使用 ZIP,Linux 发布包使用 tar.gz;所有压缩包内以 "ZCT-SLMS/" 为顶层目录。分支 push 和 PR 仅构建二进制,Docker 镜像只在推送 "v*" tag 时构建、检查和发布。

推送任意分支上的 v* tag 后,三个二进制平台构建成功,且两种 Linux 镜像完成启动检查后,发布 Docker 镜像索引和 Release。tag 含 - 为预发布,不更新 latest。

Docker 平台 独立镜像标签示例
Linux x64 (linux/amd64) ghcr.io/zct-studio/zct-slms:v2.0.1-linux-amd64
Linux ARM64 (linux/arm64) ghcr.io/zct-studio/zct-slms:v2.0.1-linux-arm64

公共版本标签(如 :v2.0.1,稳定版还有 :latest)包含这两种 Linux 架构,Docker 自动选择匹配的镜像。Windows x64 不发布 Windows 容器镜像;在 Windows 上使用 Docker Desktop 的 Linux containers 模式即可运行 Linux 镜像。版本号替换为已发布版本,例如:

docker pull ghcr.io/zct-studio/zct-slms:v2.0.1

本地构建及持久化配置继续使用现有 Compose。

本地构建

安装 CMake、受支持的 C++ 工具链及 vcpkg 依赖后执行:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2

程序位于 build/bin(多配置生成器位于 build/bin/Release)。运行时保留配置与 migrations/,工作目录应能访问这些文件。

主要功能

  • 应用资料、版本、公告、签名、加密和心跳验证。
  • 卡密生成、绑定、封禁、计时、余额与兑换码。
  • 用户、子用户、管理员和支持账号及安全验证。
  • 工单、图片材料、邮件通知、内容审查与屏蔽词过滤。

接口统一使用 /api/v1/。后端独立文档站及其 Pages 工作流暂时移除,接口参考随前端静态包提供。

许可证

见 LICENSE。

分域部署时,“前端可访问地址”用于邮件、登录完成返回和通行密钥来源;“后端可访问地址”用于 OAuth 回调,留空使用前端同域。仅配置的站点来源可跨域读取 API。前端需配置对应运行时 API 地址;OAuth 结果用短时票据与浏览器验证器交换,不依赖跨站 Cookie。

环境变量命名

运行变量统一为 ZCT_SLMS_WEB_*(前端)和 ZCT_SLMS_CORE_*(后端),构建参数统一为 ZCT_SLMS_BUILD_*。Vite 专用变量使用 VITE_ZCT_SLMS_WEB_*。Docker、GitHub 和 vcpkg 的标准变量保留工具要求的原名。完整分组、默认值和说明见 .env.example ;旧变量名称不再读取。

dotenv

后端启动时自动读取当前工作目录的 .env,文件不存在时正常启动;系统环境变量优先,文件只补充未设置的变量。同一文件中重复定义时使用最后一个值,修改后需重启。支持 UTF-8/BOM、CRLF、注释、export、单/双引号及双引号中的 \n、\r、\t 转义;不执行命令或展开变量,不支持引号跨物理行。格式错误只报告行号,不显示配置值,并中止启动。

.env 主要提供密钥、CA 路径等环境配置;业务配置仍使用 YAML。示例中的监听地址和端口变量用于 Compose 宿主机端口映射,直接运行时服务监听仍由 YAML 决定。Docker 通常由 Compose 将变量传入,无需把 .env 打入镜像。仓库仅提交 .env.example。

发布包内容

二进制包包含程序、config/config.yaml 默认配置、config/config.example.yaml、完整 migrations/、.env.example、 README.md 和 LICENSE。解压后在 ZCT-SLMS/ 目录运行程序;需要环境变量时复制 .env.example 为 .env 。更新时保留自己的配置、数据库和密钥,不要用包内默认配置覆盖现有配置。

Docker 镜像已包含运行配置、数据库迁移和许可证;.env.example 是宿主机部署模板,随二进制包和源码提供,无需写入镜像。镜像不包含本地 .env、数据库、日志或账号密钥。

C++ 与 Linux 兼容性

后端使用 C++20。Linux 发布在 Ubuntu 22.04 / Ubuntu 22.04 ARM64 上使用 GCC 13 构建(std::format 需要相应标准库支持),静态链接 libstdc++ 与 libgcc,避免要求部署系统升级 C++ 运行库。Ubuntu 22.04 与 Debian 12 的 x64、ARM64 运行兼容性由发布前手动检查。自行编译仍需支持 std::format 的 C++20 工具链。

Docker 镜像拥有独立的用户空间,基础镜像版本不等同于宿主机系统要求。

后端托管前端

将前端静态发布包解压到后端工作目录,确保 ZCT-SLMS-Web/index.html 存在(不要再多套一层同名目录)。从该工作目录启动后端,访问后端端口即可打开页面;React 页面路径支持直接访问和刷新。API 与不存在的资源仍返回 404。启动日志会打印实际静态目录。

同域托管时,runtime-config.js 的 apiBaseUrl 留空。Docker 可将前端目录只读挂载到 /app/ZCT-SLMS-Web,前端仍可独立更新。

Google 与 Telegram OAuth

安全设置支持 Google Web OAuth 客户端和 Telegram OIDC(BotFather Login Widget,RS256)。回调地址使用后端可访问地址,分别加 /api/v1/auth/connect/callback/google、/api/v1/auth/connect/callback/telegram。Telegram 还需在 Allowed URLs 中登记前端源地址及完整回调。客户端密钥加密保存,普通配置读取不返回明文。

两者沿用 state、PKCE、短时一次性票据及浏览器验证器,支持自动注册、账号绑定、二次验证与解绑工单;第三方登录不要求人机验证。Telegram ID Token 使用固定官方 JWKS 验签并校验发行方、客户端、有效期和 nonce,不信任未经验证的 JWT 内容。

版本号统一修改根目录 VERSION(支持 2.2.0-beta.1 等 SemVer 预发布版本);CMake 配置时生成版本头文件,供程序和构建使用。

推送 v* 发布标签时,CI 要求标签去掉 v 后与 VERSION 完全一致;不一致会报错并阻止发布。

图片默认保存于 data/media(Docker 已持久化该目录),数据库保存资源地址。工单图片保持加密及访问鉴权。配置 .env.example 中的 ZCT_SLMS_CORE_STORAGE_* 可使用私有 S3 兼容存储(路径式寻址、SigV4)。

升级前备份数据库、data 和身份主密钥。首次启动自动迁移旧头像、工单图片及正文内嵌图片;文件写入并读回验证成功才更新原记录,失败会阻止启动并保留未迁移数据,下次启动可重试。不要在迁移期间运行旧版本或更换存储目录、桶、端点与主密钥;切换已有存储需先复制对象。第三方头像会尝试从受信任的服务商域名下载并保存;网络不可达或域名不受支持时保留原地址,已有头像会在读取资料时再次尝试。

管理员忘记密码

在忘记密码页面选择管理员并输入用户名,确认后保存一次性显示的恢复凭证。凭证使用当前小时的 HMAC-SHA256,仅在该小时内有效;同一 IP 每 24 小时只能生成一次,重启后限制重置。无论用户名是否存在,页面都会返回同样格式的凭证。

将凭证配置为 ZCT_SLMS_CORE_ADMIN_RECOVERY_TOKEN 后重启后端。成功后查看后端日志中的临时密码,立即从环境或 .env 删除该变量,再用临时密码登录并设置新密码。恢复成功会更新密码哈希并撤销该管理员已有会话,原凭证随即失效。无效或过期凭证会记录错误并跳过重置,服务仍继续启动。Docker Compose 会传入该变量;如果身份主密钥通过 ZCT_SLMS_CORE_AUTH_MASTER_KEY 提供,恢复流程使用同一主密钥。

About

A "Cloud Verification API" using modern C++ and the Drogon Framework

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages