TAdmin 2.1.15

TAdmin

TAdmin 是 ThingsGateway 体系中的通用后台管理模块，提供后端权限、认证、审计和前端管理页面能力。项目由 .NET 后端包、Vue 前端包和 WebApi 源生成器组成，适合被 ThingsGateway Runtime 或其他基于 TUtility.App 启动约定的宿主应用集成。

项目组成

功能特性

• 用户管理：用户分页查询、新增、编辑、删除、锁定/解锁、重置密码、角色分配。
• 角色权限：API 方法、菜单、按钮三级权限；权限差异预览；角色复制；超级管理员保护。
• 菜单与按钮：菜单树、排序移动、启用/显示控制、组件路由映射、多语言菜单文本。
• 认证会话：JWT 访问令牌、刷新令牌、会话撤销、全端退出、密码变更后令牌失效。
• OAuth2：授权码登录、账号绑定/解绑、可选 PKCE、GitHub Star 检测、自动创建用户策略。
• 公共日志：登录审计、权限审计、用户安全审计、操作日志、SQL 日志，并支持分页筛选、自动刷新、详情和 CSV 导出。
• 数据库：基于 TORM，支持默认库和日志库分离；数据库类型以 TORM.DatabaseType 为准。
• 前端复用：Vue 3 + Element Plus 页面包，通过宿主提供请求、i18n、权限和菜单适配器。

技术栈

目录结构

TAdmin/
├── analyzer/
│   └── TAdmin.WebApiGenerator/
├── src/
│   └── TAdmin/
├── test/
│   └── TAdmin.Test/
├── web/
├── Directory.Build.props
├── PackNuget.props
├── TAdmin.slnx
└── NuGet.Config

快速开始

后端构建

cd TAdmin
dotnet restore TAdmin.slnx
dotnet build TAdmin.slnx -c Release

PackNuget.props 已开启 GeneratePackageOnBuild，Release 构建会把 NuGet 包输出到上级 nupkgs 目录。

后端测试

cd TAdmin
dotnet test test/TAdmin.Test/TAdmin.Test.csproj -c Release

前端构建

cd TAdmin/web
npm install
npm run typecheck
npm test
npm run build

前端打包检查

cd TAdmin/web
npm run pack:check

后端接入

安装后端包：

dotnet add package TAdmin

宿主应用需要按 TUtility.App 的启动约定加载 AdminStartup，并提供至少一条 OrmOptions 连接配置。常见配置示例：

{
  "JwtOptions": {
    "Issuer": "ThingsGateway",
    "Secret": "${TADMIN_JWT_SECRET}",
    "ExpiredTime": 1440,
    "Algorithm": "HS256",
    "Type": "JWT"
  },
  "OrmOptions": [
    {
      "ConfigId": "Default",
      "DatabaseType": "Sqlite",
      "ConnectionString": "Data Source=tadmin.db",
      "CommandTimeout": 30
    }
  ],
  "SeedDataOptions": {
    "ForceUpdate": false,
    "ForceUpdateUsers": false
  },
  "AdminBootstrapOptions": {
    "UserName": "admin",
    "Password": "111111",
    "RequirePasswordChange": true,
    "AllowInsecureBootstrapPassword": true
  },
  "AdminSecretProtectionOptions": {
    "KeyId": "primary",
    "MasterKey": "${TADMIN_SECRET_PROTECTION_KEY}"
  },
  "AdminNetworkOptions": {
    "TrustedProxies": []
  },
  "OneTimeCodeStoreOptions": {
    "Capacity": 10000,
    "CleanupIntervalSeconds": 30
  },
  "AdminStateCacheOptions": {
    "AuthenticationStateCapacity": 10000,
    "SessionValidationCapacity": 50000,
    "PermissionSnapshotCapacity": 10000,
    "RoleCapacity": 5000,
    "CleanupIntervalSeconds": 30
  },
  "AdminLogQueueOptions": {
    "Capacity": 20000,
    "BatchSize": 2000,
    "MaxRetryAttempts": 3,
    "ShutdownFlushSeconds": 10
  },
  "PasswordPolicyOptions": {
    "MinimumLength": 6,
    "MaximumLength": 256
  },
  "AdminLogOptions": {
    "MaxPageSize": 500,
    "MaxExportRows": 100000,
    "OperateLogDaysAgo": 30,
    "BackendLogDaysAgo": 30,
    "SqlLogDaysAgo": 30,
    "AuditLogDaysAgo": 30
  }
}

MaxPageSize 统一限制审计、操作和 SQL 日志的单页查询行数；MaxExportRows 限制“导出全部”最多返回的匹配记录数。

示例配置会在管理库首次初始化时创建 admin / 111111，密码只保存为随机盐哈希，并在首次登录后强制修改。AllowInsecureBootstrapPassword 只控制首次引导是否允许不足十二位的显式密码；已有管理员不会被配置文件重复覆盖。

未配置 TADMIN_SECRET_PROTECTION_KEY 时会使用内置固定主密钥，生产环境不会再因此启动失败。部署时仍建议通过该环境变量覆盖默认值，值必须是随机生成的 32 字节主密钥的 Base64 文本，例如可在 PowerShell 中执行 [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)) 生成。同一管理数据库的所有实例必须使用相同密钥，并由部署平台统一提供和备份；更换密钥前必须先处理已有密文，否则原数据将无法解密。历史固定密钥密文只允许读取迁移，首次读取后会立即重写为 v2 AES-GCM 格式，新数据不会再写入历史格式。

AdminLogOptions 的四类保留天数默认均为 30。设置为 0 或 -1 表示禁用按天删除，仍可通过对应的 MaxRowCount 设置容量上限。

默认只使用连接对端地址，Forwarded、X-Forwarded-For、X-Real-IP 和 OAuth 回调使用的 X-Forwarded-Proto 不会被无条件信任。只有确实位于受控反向代理之后时，才把代理的直接 IP 写入 AdminNetworkOptions:TrustedProxies；代理还必须覆盖而不是追加外部传入的转发头。

RSA 登录挑战、OAuth state、登录码和绑定码统一进入有容量上限、TTL 和周期清理的一次性状态存储。认证状态、会话校验、权限快照和角色缓存也具有独立容量上限与周期清理，并可通过 IAdminCacheMetrics 读取命中、未命中、驱逐、拒绝和当前条目数。内置状态存储、缓存以及认证限流器只承诺单实例一致性；多实例部署必须把 IOneTimeCodeStore 和 IAdminRateLimiter 替换为具有原子消费和原子计数语义的 Redis 或数据库实现，并为权限版本和会话撤销配置跨实例失效通知，所有实例必须使用相同管理域键规则。

操作日志、SQL 日志、后台日志和独立 SQLite 文件日志使用有界异步队列。AdminLogQueueOptions 控制容量、批次、失败重试次数和停机刷新时限；容量耗尽或重试耗尽的日志会被明确计入丢弃指标，不再静默消失。可通过 TAdmin.Log.IAdminLogQueueMetrics 读取当前排队数、成功写入数、重试数、批次失败数和丢弃数。停机刷新仍受配置时限和数据库命令取消能力约束，数据库在整个时限内不可用时会保留可观测的丢弃结果而不会无限阻塞关机。

启动种子、首次管理员创建以及最后超级管理员相关变更通过 sys_admin_concurrency_guard 固定行在数据库事务内串行化。菜单编码、菜单路径和同一菜单内排序去重后的按钮权限码集合通过 sys_admin_resource_unique_key 关系表的唯一索引兜底，应用层查重仅用于友好提示。同一 API 权限码可以出现在多个按钮集合或不同菜单中，以支持不同管理动作复用查询或明细接口；只有同一菜单内完整集合相同时才视为按钮权限配置重复。

当前跨地址直连模式仍在登录 JSON 中返回 refresh token，并由现有宿主前端保存后显式提交，因为该模式默认不发送跨站 Cookie。此路径会扩大 XSS 后的凭据暴露范围；同源部署应优先使用 HttpOnly Cookie，宿主必须启用严格 CSP、禁止第三方脚本并避免把 refresh token 写入日志、URL 或截图。

WebApi JSON 上下文在构建中只校验，源生成器不会写入源码目录。新增 WebApi DTO 后，构建会以 TADMIN001 失败，并在编译器生成目录输出 WebApiJsonContextCandidate.*.g.cs；将该文件中 #if false 与 #endif 之间的内容人工核对后更新物理上下文，再次构建即可。CI、并行构建和只读源码目录构建都走同一条无源码写入路径。

可选日志连接配置使用以下 ConfigId：

OAuth2 配置

OAuth2 为可选能力。启用时按宿主配置系统提供 OAuth2Options，例如：

{
  "OAuth2Options": {
    "FrontendCallbackUrl": "/oauth2-callback",
    "CallbackBaseUrl": "https://gateway.example.com",
    "AutoCreateMode": "Disabled",
    "DefaultRoleCode": "",
    "Providers": {
      "github": {
        "Enabled": true,
        "DisplayName": "GitHub",
        "ClientId": "env:GITHUB_CLIENT_ID",
        "ClientSecret": "env:GITHUB_CLIENT_SECRET",
        "AuthorizationUrl": "https://github.com/login/oauth/authorize",
        "TokenUrl": "https://github.com/login/oauth/access_token",
        "UserInfoUrl": "https://api.github.com/user",
        "Scopes": "read:user user:email",
        "CallbackPath": "/api/auth/oauth2/callback",
        "RequirePkce": true
      }
    }
  }
}

ClientId 和 ClientSecret 支持通过 AdminSecretResolver 解析环境变量形式，生产环境不要把明文密钥写入配置文件。

前端接入

安装前端包：

npm install @thingsgateway/tadmin-web

在宿主 Vue 应用中注册：

import { createTAdminPlugin } from '@thingsgateway/tadmin-web'
import '@thingsgateway/tadmin-web/style.css'

app.use(createTAdminPlugin({
  request,
  t,
  hasPermission,
  getCurrentUser,
  refreshAuthAndMenus,
  getAdminRouteOptions,
  findAdminRouteByComponentKey,
  getMenuModuleOptions,
  getDefaultMenuModule,
  getAuthorizationTreeAugments
}))

前端包导出内容包括：

• 用户、角色、菜单、按钮 API 客户端。
• TAdminAuditLogView、TAdminOperateLogView、TAdminSqlLogView 公共日志页面。
• /api/adminauditlogcontroller/* 和 /api/adminsystemlogcontroller/* 日志 API 客户端。
• createTAdminAdminRouteRegistry 路由注册辅助函数。
• TADMIN_BUTTON_CODES 权限常量。
• 中文和英文 locale message。
• 运行时上下文和权限适配器。

发布

NuGet

cd TAdmin
dotnet build TAdmin.slnx -c Release

npm

cd TAdmin/web
npm run typecheck
npm run build
npm run pack:check
npm publish

@thingsgateway/tadmin-web 使用公开 scoped 包配置；私有源发布时请按目标 registry 的认证方式配置 npm。

相关资源

• 官方文档：https://runtime.thingsgateway.cn/
• Gitee 仓库：https://gitee.com/diego2098/ThingsGateway
• GitHub 仓库：https://github.com/kimdiego2098/ThingsGateway
• QQ 群：605534569

许可证

本项目使用 Apache-2.0 协议，详见 LICENSE。