TDengine 用户管理完全指南：创建、查询、修改与安全策略（含 TOTP 双因素认证与 Token 管理）

TDengine 用户管理完全指南：创建、查询、修改与安全策略（含 TOTP 双因素认证与 Token 管理）

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine

本文是 TDengine 时间序列数据库用户管理体系的实战指南，围绕CREATE USER、SHOW USERS、ALTER USER、DROP USER等 SQL 语句展开，覆盖密码策略、会话与登录限制、IP 白名单/黑名单、基于时间的登录时段控制、TOTP 双因素认证以及 Token 令牌管理等企业级安全能力。读完本文，你将能够在 taos shell 或业务代码中完整地完成用户的创建、授权边界设定、安全加固与生命周期管理，并理解这些语法背后的服务端实现原理。

功能概述与版本说明

TDengine 的用户管理语法在社区版与企业版中均可使用，但功能可用性存在差异：社区版（TDengine TSDB Community Edition）仅开放基础功能，高级安全能力（会话限制、密码策略、IP 白名单、TOTP、Token 等）属于**企业版（TDengine TSDB Enterprise Edition）**特性。文中各参数后标注了引入版本，例如SESSION_PER_USER等会话与密码策略参数支持于企业版 v3.4.0.0 及以上，TOTP 双因素认证支持于 v3.4.0.1 及以上。

需要说明的是，社区版虽然可以执行 IP 白名单、Token 等语句，但不会强制执行对应限制，相关安全策略只有在企业版中才真正生效。

创建用户：CREATE USER

创建用户的完整语法如下：

CREATE USER user_name PASS 'password' [SYSINFO {1|0}] [CREATEDB {1|0}] [ENABLE {1|0}] [CHANGEPASS {2|1|0}] [SESSION_PER_USER {value | DEFAULT | UNLIMITED}] [CONNECT_TIME {value | DEFAULT | UNLIMITED}] [CONNECT_IDLE_TIME {value | DEFAULT | UNLIMITED}] [CALL_PER_SESSION {value | DEFAULT | UNLIMITED}] [VNODE_PER_CALL {value | DEFAULT | UNLIMITED}] [FAILED_LOGIN_ATTEMPTS {value | DEFAULT | UNLIMITED}] [PASSWORD_LOCK_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_LIFE_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_GRACE_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_REUSE_TIME {value | DEFAULT}] [PASSWORD_REUSE_MAX {value | DEFAULT}] [INACTIVE_ACCOUNT_TIME {value | DEFAULT | UNLIMITED}] [ALLOW_TOKEN_NUM {value | DEFAULT | UNLIMITED}] [SECURITY_LEVEL min_level, max_level] [HOST {ip | ip range} [, {ip | ip range}] ...] [NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...] [ALLOW_DATETIME {time range} [, {time range}] ...] [NOT_ALLOW_DATETIME {time range} [, {time range}] ...]

命名与密码约束：

• 用户名最长23 字节。
• 密码长度必须为8 到 255 个字符，且必须包含大写字母、小写字母、数字、特殊字符四类中的至少三类。特殊字符包括：! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .。
• 强密码校验可以通过在taos.cfg中设置enableStrongPassword 0关闭，也可以通过 SQL 动态关闭：

alter all dnodes 'EnableStrongPassword' '0'

从源码看，密码格式校验位于 mndUser.c 的mndCheckCreateUserReqPasswordFmt：当tsEnableStrongPassword == 0时允许简单密码；否则依次校验最小长度（TSDB_PASSWORD_MIN_LEN）、最大长度（TSDB_PASSWORD_MAX_LEN）与复杂度（isComplexPass），任一不满足即返回TSDB_CODE_MND_INVALID_PASS_FORMAT或对应长度错误码。

各选项说明

登录时间段的组合语义

• 两者均未设置：任何时间均可登录。
• 仅设置ALLOW_DATETIME：仅在该时间段内允许登录。
• 仅设置NOT_ALLOW_DATETIME：仅禁止在该时间段内登录。
• 两者均设置：仅允许在属于ALLOW_DATETIME且不属于NOT_ALLOW_DATETIME的时间登录。

关于 enableAdvancedSecurity

FAILED_LOGIN_ATTEMPTS等选项的默认值取决于配置参数enableAdvancedSecurity。该参数默认开启（源码中int8_t tsEnableAdvancedSecurity = 1;，见 tglobal.c），属于全局安全类配置（CFG_PRIV_SECURITY）。可通过 SQL 动态切换：

-- 开启高级安全（默认） alter all dnodes 'EnableAdvancedSecurity' '1' -- 关闭高级安全 alter all dnodes 'EnableAdvancedSecurity' '0'

关闭高级安全后，密码校验逻辑相应放宽：在 mndUser.c 中，当tsEnableAdvancedSecurity == 0且使用默认密码时直接放行，不再强制复杂密码。

创建用户示例

创建一个密码为abc123!@#、可查看系统信息的用户test：

taos> create user test pass 'abc123!@#' sysinfo 1; Query OK, 0 of 0 rows affected (0.001254s)

查看用户：SHOW USERS 与系统表

查看系统中全部用户：

SHOW USERS;

示例输出：

taos> show users; name | super | enable | sysinfo | createdb | create_time | totp | allowed_host | allowed_datetime | ============================================================================================================================================ test | 0 | 1 | 1 | 0 | 2025-12-24 18:56:20.709 | 0 | +127.0.0.1/32, +::1/128 | +ALL | root | 1 | 1 | 1 | 1 | 2025-12-24 18:00:43.197 | 0 | +127.0.0.1/32, +::1/128 | +ALL | Query OK, 2 rows in set (0.001657s)

输出列说明：allowed_host中地址前缀+表示白名单条目（允许登录），前缀-表示黑名单条目（禁止登录）；allowed_datetime同理。totp列为1表示该用户已启用 TOTP 双因素认证。

也可以查询内置系统表INFORMATION_SCHEMA.INS_USERS获取相同的用户信息：

taos> select * from information_schema.ins_users; name | super | enable | sysinfo | createdb | create_time | totp | allowed_host | allowed_datetime | ============================================================================================================================================ test | 0 | 1 | 1 | 0 | 2025-12-24 18:56:20.709 | 0 | +127.0.0.1/32, +::1/128 | +ALL | root | 1 | 1 | 1 | 1 | 2025-12-24 18:00:43.197 | 0 | +127.0.0.1/32, +::1/128 | +ALL | Query OK, 2 row(s) in set (0.007383s)

在仓库的 mnode 单元测试 user.cpp 中，可以看到通过TSDB_MGMT_TABLE_USER消息类型配合ins_users表名来批量验证用户信息的测试模式，这印证了SHOW USERS与INFORMATION_SCHEMA.INS_USERS底层共享同一份用户元数据。

删除用户：DROP USER

DROP USER [IF EXISTS] user_name;

IF EXISTS可避免用户不存在时报错。注意：删除用户时，该用户拥有的 Token 会被级联删除。

修改用户：ALTER USER

修改用户配置的完整语法：

ALTER USER user_name alter_user_clause alter_user_clause: { [PASS 'password'] [SYSINFO {1|0}] [CREATEDB {1|0}] [ENABLE {1|0}] [CHANGEPASS {2|1|0}] [SESSION_PER_USER {value | DEFAULT | UNLIMITED}] [CONNECT_TIME {value | DEFAULT | UNLIMITED}] [CONNECT_IDLE_TIME {value | DEFAULT | UNLIMITED}] [CALL_PER_SESSION {value | DEFAULT | UNLIMITED}] [VNODE_PER_CALL {value | DEFAULT | UNLIMITED}] [FAILED_LOGIN_ATTEMPTS {value | DEFAULT | UNLIMITED}] [PASSWORD_LOCK_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_LIFE_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_GRACE_TIME {value | DEFAULT | UNLIMITED}] [PASSWORD_REUSE_TIME {value | DEFAULT}] [PASSWORD_REUSE_MAX {value | DEFAULT}] [INACTIVE_ACCOUNT_TIME {value | DEFAULT | UNLIMITED}] [ALLOW_TOKEN_NUM {value | DEFAULT | UNLIMITED}] [SECURITY_LEVEL min_level, max_level] [ADD HOST {ip | ip range} [, {ip | ip range}] ...] [DROP HOST {ip | ip range} [, {ip | ip range}] ...] [ADD NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...] [DROP NOT_ALLOW_HOST {ip | ip range} [, {ip | ip range}] ...] [ADD ALLOW_DATETIME {time range} [, {time range}] ...] [DROP ALLOW_DATETIME {time range} [, {time range}] ...] [ADD NOT_ALLOW_DATETIME {time range} [, {time range}] ...] [DROP NOT_ALLOW_DATETIME {time range} [, {time range}] ...] }

各选项含义与CREATE USER一致；DEFAULT表示恢复默认值，UNLIMITED表示解除限制。

示例：禁用用户test：

taos> alter user test enable 0; Query OK, 0 of 0 rows affected (0.001160s)

改密后的会话处理机制

修改用户密码（ALTER USER ... PASS）后，服务端会在心跳检测时发现仍使用旧密码的既有会话并将其断开，这些连接上的后续请求会返回认证失败错误码0x80000357；执行改密的连接本身不受影响。需要特别注意的是，使用 Token 认证的连接不受此机制约束。

SYSINFO 与角色的联动

自企业版 v3.4.2.1 起，ALTER USER ... SYSINFO {0|1}会同步更新用户的SYSINFO_0/SYSINFO_1角色；反过来，授予更高系统角色也会提升SYSINFO属性。详见授权管理中的联动说明。

IP 白名单与黑名单（HOST / NOT_ALLOW_HOST）

IP 白名单/黑名单用于限制用户可登录的源地址，与GRANT权限体系相互独立管理。企业版自 v3.2.0.0 起提供白名单能力，HOST/NOT_ALLOW_HOST语法自 v3.4.0.0 起支持。社区版可以执行增删改查语句，但不强制执行源 IP 限制。设置系统配置enableWhiteList为1后白名单/黑名单才生效（见 taosd）。该配置默认值为false（源码见 tglobal.c），属于系统类动态配置（CFG_DYN_SERVER，CFG_PRIV_SYSTEM）。

登录判定规则

• 若HOST与NOT_ALLOW_HOST均未设置，用户可从任意地址登录。注意：出于安全与便利考虑，创建用户时若设置了HOST，或两者均未设置，系统会自动将127.0.0.1和::1加入HOST。因此"任意地址"的情形只会在通过ALTER USER将HOST与NOT_ALLOW_HOST全部删除后出现。
• 仅设置HOST：只允许从这些地址/网段登录。
• 仅设置NOT_ALLOW_HOST：禁止从这些地址/网段登录，其余地址允许。
• 两者均设置：仅允许从属于HOST且不属于NOT_ALLOW_HOST的地址登录。

从创建用户的实现看（mndUser.c）：当创建请求未携带任何 IP 范围时，调用createDefaultIpWhiteList生成默认白名单；当携带了正向（非neg）范围时，会通过addDefaultIpToTable自动补充本机 IP；范围总数超过MND_MAX_USER_IP_RANGE时返回TSDB_CODE_MND_TOO_MANY_USER_IP_RANGE。

添加与查询示例

添加 IP 白名单：

CREATE USER test PASS 'taosdata1' HOST '192.168.1.0/24', '10.0.0.1'; ALTER USER test ADD HOST '192.168.2.0/24';

添加 IP 黑名单：

ALTER USER test ADD NOT_ALLOW_HOST '203.0.113.5/32';

查询：

SELECT name, allowed_host FROM information_schema.ins_users; SHOW USERS;

allowed_host中+前缀表示白名单（允许登录），-前缀表示黑名单（禁止登录）。

移除条目：

ALTER USER test DROP HOST '192.168.2.0/24'; ALTER USER test DROP NOT_ALLOW_HOST '203.0.113.5/32';

使用注意事项

• 社区版与企业版均可添加和查询条目，但社区版不强制执行 IP 限制。
• 可一次添加多个 IP 范围，服务端仅对完全相同的条目去重。例如：CREATE USER u_write PASS 'taosdata1' HOST 'iprange1','iprange2'。
• 127.0.0.1默认加入白名单且在查询中可见（部分文档场景还会包含::1）。
• 集群节点 IP 集合会自动加入白名单，但查询中不可见。
• 当taosAdapter与taosd不在同一主机时，需手动将taosAdapter的 IP 加入taosd的白名单。
• 集群中enableWhiteList必须在各节点保持一致（全部false或全部true），否则集群无法启动。
• 白名单变更约 1 秒（不超过 2 秒）生效；变更本身对收发性能影响可忽略，变更完成后无持续影响；不影响已入白名单 IP 的集群与客户端。
• 若添加了存在包含关系的两个网段（如 A：192.168.1.1/16与 B：192.168.1.1/24），由于情形复杂不会被合并。
• 删除必须精确匹配：添加的是192.168.1.1/24，就必须删除192.168.1.1/24。
• 只有root可以为其他用户添加或删除白名单条目。
• 兼容旧版本，但不支持从当前版本回滚到旧版本。
• x.x.x.x/32与x.x.x.x等价，展示为x.x.x.x。
• 客户端收到0.0.0.0/0表示白名单未启用。
• 白名单变更后，客户端通过心跳感知。
• 单用户最大 IP 数为2048。

TOTP 双因素认证

TOTP 双因素认证是企业版特性，支持版本 v3.4.0.1 及以上。启用后，客户端登录时除密码外还需提供 TOTP 动态验证码。

创建/更新 TOTP 密钥

CREATE TOTP_SECRET FOR USER user_name

若用户尚未创建 TOTP 密钥，该命令会为其生成；若已存在，则更新密钥。无论哪种情况，命令都会返回新生成的密钥，该密钥仅显示一次，请及时妥善保存。系统会自动为拥有 TOTP 密钥的用户启用双因素认证。

启用后，TDengine 要求 OTP 为6 位数字、每 30 秒刷新一次。请据此配置你的 TOTP 生成器（如 Google Authenticator、1Password 等），否则客户端可能登录失败。

为test用户创建 TOTP 密钥示例：

taos> create totp_secret for user test; totp_secret | ======================================================= ERIRPLZL4ZBFTPT5BNXMVFPR4Z3PTHUWTBTCNZPOHYPYQGTD25XA | Query OK, 1 row(s) in set (0.002314s)

在服务端创建用户的实现中（mndUser.c），当请求携带totpseed时，会调用taosGenerateTotpSecret生成 TOTP 种子并存入用户对象，生成失败则返回TSDB_CODE_PAR_INVALID_OPTION_VALUE。

删除 TOTP 密钥

DROP TOTP_SECRET FROM USER user_name

删除后该用户的 TOTP 双因素认证即被禁用。示例：

taos> drop totp_secret from user test; Drop OK, 0 row(s) affected (0.002295s)

Token 令牌管理

Token 管理是企业版特性，支持版本 v3.4.0.0 及以上。Token 可替代密码用于连接认证，且不受"改密即断开旧会话"机制影响，适合服务间调用等场景。

创建 Token

CREATE TOKEN [IF NOT EXISTS] token_name FROM USER user_name [ENABLE {1|0}] [TTL value] [PROVIDER value] [EXTRA_INFO value]

• token_name最长31 字节。
• ENABLE：Token 是否启用，1启用、0禁用；禁用的 Token 无法用于连接数据库。默认1。
• TTL：有效期（天），从创建时间起算。默认0表示永久有效。
• PROVIDER：Token 提供方名称，最长63 字节。
• EXTRA_INFO：由应用管理的附加信息，最长1023 字节。

示例：为test用户创建名为test_token的 Token。Token 值仅在创建时显示一次，之后无法再查询，请及时保存：

taos> create token test_token from user test; token | ================================================================== BsyjYKxhCMntZ3pHgweCd2uV2C8HoGKn8Mvd49dRRCtzusX0P1mgqRMrG7SzUca | Query OK, 1 row(s) in set (0.003018s)

查看 Token

SHOW TOKENS;

根据权限不同，你可能只能看到自己的 Token。示例：

taos> show tokens; name | user | provider | enable | create_time | expire_time | extra_info | ========================================================================================================= root_token | root | | 1 | 2025-12-25 10:02:28.000 | 1970-01-01 08:00:00.000 | | test_token | test | | 1 | 2025-12-25 10:01:47.000 | 1970-01-01 08:00:00.000 | | Query OK, 2 row(s) in set (0.003313s)

也可查询内置系统表INFORMATION_SCHEMA.INS_TOKENS：

taos> select * from information_schema.ins_tokens; name | user | provider | enable | create_time | expire_time | extra_info | ========================================================================================================= root_token | root | | 1 | 2025-12-25 10:02:28.000 | 1970-01-01 08:00:00.000 | | test_token | test | | 1 | 2025-12-25 10:01:47.000 | 1970-01-01 08:00:00.000 | | Query OK, 2 row(s) in set (0.007438s)

修改 Token

ALTER TOKEN token_name [ENABLE {1|0}] [TTL value] [PROVIDER value] [EXTRA_INFO value]

注意：修改有效期（TTL）时，新的有效期从修改时刻重新起算。

删除 Token

DROP TOKEN [IF EXISTS] token_name;

删除用户时，其名下 Token 会被级联删除。

用户管理实践要点

1. 密码策略分层落地：默认enableStrongPassword=1、enableAdvancedSecurity=1（源码默认值见 tglobal.c）。生产环境建议保持开启；若确需弱口令（如仅限内网的测试环境），可通过alter all dnodes 'EnableStrongPassword' '0'关闭强密码校验。
2. 访问控制按需收紧：为每个应用分配独立账号，按最小权限原则设置SYSINFO、CREATEDB，并通过HOST/NOT_ALLOW_HOST限制登录来源，通过ALLOW_DATETIME/NOT_ALLOW_DATETIME限制登录时段。
3. 账号生命周期管理：使用ENABLE 0临时冻结账号、FAILED_LOGIN_ATTEMPTS+PASSWORD_LOCK_TIME防暴力破解、PASSWORD_LIFE_TIME+PASSWORD_GRACE_TIME强制定期改密、INACTIVE_ACCOUNT_TIME清理僵尸账号。
4. 会话与资源限制：通过SESSION_PER_USER、CONNECT_TIME、CONNECT_IDLE_TIME、CALL_PER_SESSION、VNODE_PER_CALL防止单账号过度占用连接与计算资源。
5. 认证强度升级：对核心账号启用 TOTP 双因素认证；对自动化任务与微服务间调用改用 Token 认证，避免共享密码，同时利用TTL、PROVIDER、EXTRA_INFO做好 Token 的周期轮换与归属管理。
6. 权限联动意识：SYSINFO属性与系统角色存在联动关系，改密会影响旧密码会话，集群部署时enableWhiteList必须全集群一致——这些隐含规则是排障时最容易忽略的点。

以上语法与行为均可在当前仓库中验证：用户管理的服务端核心实现在 mndUser.c，相关安全/系统配置注册于 tglobal.c，用户与 Token 的元数据查询（ins_users/ins_tokens）在 user.cpp 中亦有覆盖测试。

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine