修bug，完善功能

2026-10-16 23:52:12 +08:00
1 parent 30364b1c4b
commit 6996e19694
@@ -2,7 +2,17 @@

 [← 返回 README](../README.md)

-**本页导航：** [root 的含义](#root-的含义) · [默认属性与修改方法](#默认属性与修改方法) · [全部身份及凭据字段](#全部身份及凭据字段) · [本机 sudo 认证](#本机-sudo-认证) · [对象授权](#对象授权) · [属性、授权与会话的关系](#属性授权与会话的关系) · [升级兼容](#升级兼容)
+本页内容：
+
+- [root 的含义](#root-的含义)
+- [默认属性与修改方法](#默认属性与修改方法)
+- [全部身份及凭据字段](#全部身份及凭据字段)
+- [本机 sudo 认证](#本机-sudo-认证)
+- [对象授权](#对象授权)
+- [属性、授权与会话的关系](#属性授权与会话的关系)
+- [升级兼容](#升级兼容)
+
+本页帮助管理员理解身份属性、配置本机认证和授予对象权限。SQL 命令示例集中在 [SQL 语法](syntax.md#账号与权限)。

 ChuSQL 的用户和角色共用一套身份目录及名称空间。用户是允许登录的角色；`CREATE USER` 与 `CREATE ROLE` 的主要区别是默认登录能力。同名用户和角色不能同时存在。

@@ -34,15 +44,32 @@ ChuSQL 的用户和角色共用一套身份目录及名称空间。用户是允

 身份创建与修改语法见 [SQL 语法](syntax.md#账号与权限)。

-`ALTER USER` 与 `ALTER ROLE` 的属性、口令修改语法通用。可使用 `LOGIN / NOLOGIN`、`SUPERUSER / NOSUPERUSER`、`ENABLED / DISABLED`、`SYSTEM_CATALOG_MANAGER / NOSYSTEM_CATALOG_MANAGER`、`ALLOW_SUDO_AUTH / NOALLOW_SUDO_AUTH`；同一条语句不能重复指定同一属性。
+`ALTER USER` 与 `ALTER ROLE` 的属性、口令修改语法通用。同一条语句不能重复指定同一属性。可修改的属性如下：

-SUPERUSER 可设置目录管理属性。该属性默认为 false，不经成员关系继承；只有自身启用且允许登录的身份能使用它。目录管理者可以进入 system 库、查看身份目录、创建普通身份、修改普通身份属性与口令及删除普通用户身份。它不能管理 SUPERUSER、其他目录管理者或启用 sudo 认证的身份，不能授予这三个特权属性，不能执行 `DROP ROLE`，也不会因此获得创建业务数据库、直接修改系统表或读取业务数据的权限。受限身份变更在存储写锁内再次检查目标权限。
+| 属性 | 开启 / 关闭 |
+| --- | --- |
+| 登录能力 | `LOGIN / NOLOGIN` |
+| 最高权限 | `SUPERUSER / NOSUPERUSER` |
+| 启用状态 | `ENABLED / DISABLED` |
+| 受限目录管理 | `SYSTEM_CATALOG_MANAGER / NOSYSTEM_CATALOG_MANAGER` |
+| 本机 sudo 认证 | `ALLOW_SUDO_AUTH / NOALLOW_SUDO_AUTH` |

-<details>
-<summary><strong>身份与凭据的内部字段</strong></summary>
+### 受限的目录管理能力
+
+SUPERUSER 可设置目录管理属性。该属性默认为 false，不经成员关系继承；只有自身启用且允许登录的身份能使用它。
+
+目录管理者可以进入 system 库、查看身份目录、创建普通身份、修改普通身份属性与口令及删除普通用户身份。目录管理者受到以下限制：
+
+- 不能管理 SUPERUSER、其他目录管理者或启用 sudo 认证的身份，也不能授予这三个特权属性。
+- 不能执行 `DROP ROLE`。
+- 不会因此获得创建业务数据库、直接修改系统表或读取业务数据的权限。
+
+受限身份变更在存储写锁内再次检查目标权限。

 ## 全部身份及凭据字段

+本节供维护系统目录和协议时查阅，日常授权可直接阅读[本机 sudo 认证](#本机-sudo-认证)或[对象授权](#对象授权)。
+
 身份元数据保存于隐藏的 `system.__system_identities`；凭据单独保存于 `system.__system_users`。以下字段解释实际持久化内容，不表示都能通过 SQL 修改或查询。

 | 身份字段 | 含义 | 管理方式 |
@@ -66,13 +93,15 @@ SUPERUSER 可设置目录管理属性。该属性默认为 false，不经成员

 内部账号协议可将身份字段和 `password_hash` 合并为账号对象，但哈希不属于公开的角色展示内容。`SHOW ROLES` 展示全部身份的编号、名称、登录能力、最高权限、启用状态、目录管理属性、sudo 认证开关和创建时间，不返回口令哈希，也不展示全部内部字段。系统表由身份管理接口维护，不应直接修改。

-</details>
-
 ## 本机 sudo 认证

-此入口适用于 Linux、macOS 和 Windows，默认关闭。Unix 有效 UID 0（通常通过 sudo 获得）映射到 `[server] sudo_auth_user`；Windows 提升令牌中的 Administrators 成员映射到同一配置身份。不会使用客户端上报的操作系统用户名、`SUDO_USER`、数据库用户名或角色属性作为操作系统身份凭据。
+本机 sudo 认证允许受信任的操作系统管理员免数据库口令登录指定身份，默认关闭。入口面向 Linux、macOS 和 Windows；各平台尚待验收的路径见[当前限制](../.agents/context/known-issues.txt)。

-先用数据库 SUPERUSER 配置目标身份，例如：
+Unix 有效 UID 0（通常通过 sudo 获得）映射到 `[server] sudo_auth_user`；Windows 提升令牌中的 Administrators 成员映射到同一配置身份。不会使用客户端上报的操作系统用户名、`SUDO_USER`、数据库用户名或角色属性作为操作系统身份凭据。
+
+### 配置身份与映射
+
+先确保目标身份已创建，再用数据库 SUPERUSER 配置，例如：

 ```sql
 ALTER USER local_operator ALLOW_SUDO_AUTH;
@@ -87,25 +116,37 @@ ALTER USER local_operator ALLOW_SUDO_AUTH;
 sudo_auth_user = "local_operator"
 ```

+### 提升身份后登录
+
 停止原服务后，以 Unix root 或 Windows 提升后的管理员重启 `chusql-server`，使用受管理员保护的配置文件、数据目录和程序路径。以相同提升身份运行 CLI；Unix 示例：

 ```sh
 sudo csql --config /absolute/path/settings.toml --sudo -e "SELECT 1"
 ```

-Windows 在提升的终端中运行 `csql --config C:\absolute\path\settings.toml --sudo -e "SELECT 1"`。`--sudo` 不读取数据库口令，省略 `--user` 时使用配置映射。显式指定其他账号也不能绕过服务端映射。普通 TCP/CLI 口令登录与 Web 登录保持原有口令认证；远程连接无法请求此入口，CLI 也校验实际连接对端为回环地址。
+Windows 在提升的终端中运行 `csql --config C:\absolute\path\settings.toml --sudo -e "SELECT 1"`。`--sudo` 不读取数据库口令，省略 `--user` 时使用配置映射。显式指定其他账号也不能绕过服务端映射。

-<details>
-<summary><strong>凭据保护、认证协议与异常清理</strong></summary>
+普通 TCP/CLI 口令登录与 Web 登录保持原有口令认证；远程连接无法请求此入口，CLI 也校验实际连接对端为回环地址。

-服务启动时产生独立随机凭据。Unix 放在 `/var/run/chusql-sudo-<实际端口>/credential`，目录 root 所有且为 0700，文件为 0600；Windows 放在系统目录的 `config\ChuSQL-Sudo-<实际端口>\credential`，使用不继承的 Administrators / SYSTEM 专属 DACL。读取入口检查当前进程提升身份；Unix 还验证文件所有权、权限和类型，拒绝链接，Windows 拒绝重解析路径。凭据不会传输到网络，CLI 使用 HMAC-SHA256 回应绑定连接、账号和服务实例的一次性随机挑战；挑战 60 秒后过期，每次认证尝试都会消费挑战，失败按账号限流。
+### 凭据保护与认证协议

-服务端在 stderr 记录启用映射和认证结果，不记录凭据或证明。成功登录更新身份目录的 `last_login_at`。`ALTER USER local_operator NOALLOW_SUDO_AUTH`、`DISABLED`、`NOLOGIN`、修改口令或删除身份都会使既有连接在下一次请求时失效。映射配置清空并重启服务后，本机入口关闭。
+服务启动时产生独立随机凭据，保存位置和权限如下：
+
+- Unix 放在 `/var/run/chusql-sudo-<实际端口>/credential`，目录 root 所有且为 0700，文件为 0600。
+- Windows 放在系统目录的 `config\ChuSQL-Sudo-<实际端口>\credential`，使用不继承的 Administrators / SYSTEM 专属 DACL。
+
+读取入口检查当前进程提升身份；Unix 还验证文件所有权、权限和类型，拒绝链接，Windows 拒绝重解析路径。
+
+凭据不会传输到网络，CLI 使用 HMAC-SHA256 回应绑定连接、账号和服务实例的一次性随机挑战；挑战 60 秒后过期，每次认证尝试都会消费挑战，失败按账号限流。
+
+服务端在 stderr 记录启用映射和认证结果，不记录凭据或证明。
+
+成功登录更新身份目录的 `last_login_at`。`ALTER USER local_operator NOALLOW_SUDO_AUTH`、`DISABLED`、`NOLOGIN`、修改口令或删除身份都会使既有连接在下一次请求时失效。映射配置清空并重启服务后，本机入口关闭。
+
+### 异常退出后的清理

 正常停止服务时清理凭据。异常退出可能留下端口专属目录；再次启用会明确报错，不读取或覆盖旧凭据。确认对应服务已停止后，由提升身份清理该目录再启动；不要把凭据复制到普通账号可访问的目录。

-</details>
-
 ## 对象授权

 业务授权绑定数据库编号与表编号，身份与所有者绑定身份编号。删除后重建同名数据库、表或身份会获得新编号，旧授权不会随名称恢复。对象存在性以 catalog 为准；不同数据库的同名表互不共享授权。
@@ -118,6 +159,8 @@ Windows 在提升的终端中运行 `csql --config C:\absolute\path\settings.tom

 `ALL` 按对象范围展开。未限定表名与 `*` 绑定当前数据库。数据库所有权不自动赋予其他身份所建表的数据权限；启用的所有者角色可以通过成员关系贡献所有权，最高权限属性仍不继承。创建数据库及管理 DOMAIN 仍要求 SUPERUSER；所有权不能通过 REVOKE 移除，当前没有所有权转移命令。

+例如，以下命令撤销默认连接权限，并分别授予数据库和表权限：
+
 ```sql
 REVOKE CONNECT ON DATABASE sales FROM PUBLIC;
 GRANT CONNECT, CREATE ON DATABASE sales TO analyst;
@@ -126,11 +169,21 @@ GRANT SELECT ON sales.* TO analyst;
 REVOKE SELECT ON sales.orders FROM reader;
 ```

+### PUBLIC 默认连接权限
+
 PUBLIC 是所有身份共享的虚拟角色，不能新建同名用户或角色。已有同名旧身份仍按真实身份编号解析，删除该身份后才使用虚拟 PUBLIC。撤销 PUBLIC CONNECT 会关闭数据库的默认连接权限，其他显式 CONNECT 或数据库所有权仍有效；重新授予会恢复默认连接权限。

-每次授予记录授予者。普通身份须持有有效 grant option 或对象所有权，可撤销自己的授予；所有者和 SUPERUSER 可撤销对象上的其他来源。撤销、删除身份或成员变更会清理失去合法来源的转授权链；其他独立来源保留，循环转授不能维持失去根来源的权限。禁用身份暂停权限贡献，保留所有权及管理员直接授权；失去启用授予者的下游转授权会被清理。
+### 转授权的来源与撤销

-权限快照位于受保护系统目录，经 WAL 原子保存；普通存储请求不能访问该目录。SQL、TCP 和 Web 使用同一服务端检查；TCP 原始存储入口仅允许 SUPERUSER。查询与授权变更通过共享读写锁排序，建表前持久化创建者声明供重启恢复所有权。事务提交重新检查权限和稳定对象编号，权限撤销或对象替换后不能提交旧事务。
+转授权能力（grant option）允许身份将持有的权限授予其他身份。每次授予记录授予者。普通身份须持有有效 grant option 或对象所有权，可撤销自己的授予；所有者和 SUPERUSER 可撤销对象上的其他来源。
+
+撤销、删除身份或成员变更会清理失去合法来源的转授权链；其他独立来源保留，循环转授不能维持失去根来源的权限。禁用身份暂停权限贡献，保留所有权及管理员直接授权；失去启用授予者的下游转授权会被清理。
+
+### 权限持久化与提交复查
+
+权限快照位于受保护系统目录，经 WAL 原子保存；普通存储请求不能访问该目录。SQL、TCP 和 Web 使用同一服务端检查；TCP 原始存储入口仅允许 SUPERUSER。查询与授权变更通过共享读写锁排序，建表前持久化创建者声明供重启恢复所有权。
+
+事务提交重新检查权限和稳定对象编号，权限撤销或对象替换后不能提交旧事务。

 ## 属性、授权与会话的关系