大更新：

1、完善SQL语法 2、移除node前端，只保留静态资源 3、写好安装脚本 4、做好linux适配
2026-10-01 20:48:38 +08:00
1 parent 687c012841
commit df6d348995
@@ -0,0 +1,142 @@
+# 命令与选项
+
+## 一共有几个可执行文件
+
+| 命令 | 作用 | 选项 |
+| ---- | ---- | ---- |
+| `chusql-storage` | 存储进程：页面与索引、WAL | 只有 `--config <path>` |
+| `chusql-web` | Web 管理端：REST 接口 + 浏览器里的数据库 IDE | 见「`chusql-web` 选项」 |
+| `csql` | 命令行客户端，直连存储进程，不经过 HTTP | 见「`csql` 选项」 |
+| `csql-web` | 一键启动器：按配置拉起存储进程 + Web，日志写 `<install-dir>/logs` | 无选项（`host`/`port` 从配置读） |
+
+四个命令共用同一份 [`chusql.toml`](config.md)；`--config` 都是用来临时读另一份配置的。
+
+## `csql` 选项
+
+    csql [options]
+
+| 选项 | 默认 | 说明 |
+| ---- | ---- | ---- |
+| `-u, --user USER` | 配置里的管理员 | 用这个账号登录 |
+| `-p, --password` | — | 强制交互输入口令，忽略配置里的 |
+| `-d, --database DB` | 不选（启动后没有默认库） | 登录后直接选中哪个库 |
+| `-f, --format FORMAT` | `table` | 输出格式：`table` / `json` / `csv` |
+| `-e, --execute SQL` | — | 跑一条语句就退出（脚本化用） |
+| `--history FILE` | `~/.chusql_history` | 历史文件位置 |
+| `--pipe NAME` | 配置 `[server] pipe_name` | 端点名（Windows 具名管道 / Unix 套接字文件） |
+| `--storage SERVER` | — | 端点没人应答时，拉起这个存储进程可执行文件 |
+| `--config FILE` | 固定位置的 `chusql.toml` | 读另一份配置 |
+| `-h, --help` | — | 帮助 |
+
+脚本化示例：
+
+    csql -e "SELECT count(*) FROM orders" -f json
+    csql -u analyst -p -d sales -f csv -e "SELECT * FROM orders LIMIT 5"
+
+## 交互模式
+
+- 提示符 `chusql>`；语句以**分号**结尾，可以跨多行；上下键翻历史（默认存 `~/.chusql_history`）。
+- 退出码：语句出错时非 0，方便在脚本里判断。
+
+### 元命令
+
+| 元命令 | 作用 |
+| ------ | ---- |
+| `\q` `\quit` | 退出 |
+| `\?` `\h` `\help` | 帮助 |
+| `\l` `\list` | 列出数据库 |
+| `\dt` `\d` | 列出当前库的表 |
+| `\d <表>` | 看表结构 |
+| `\dr` `\roles` | 角色总览：授权对象与成员（管理员专属，等价于 Web 的 `GET /api/roles`） |
+| `\c <库>` | 切换数据库 |
+| `\f` `\format <fmt>` | 切换输出格式：`table` / `json` / `csv` |
+
+普通身份用 `\dt` 时只会看到自己有 `SELECT` 权限的表，系统表永远不出现。
+
+## 账号与权限
+
+账号：root（配置里的 `user` / `password` 决定，见 [config.md](config.md)）是管理员，其余都是普通账号，
+默认**零权限**，只能看到被授权的表。系统库 `system`（账号表在里面）只有管理员能进。
+
+服务启动后**只有系统库**，没有任何默认工作库：自己 `CREATE DATABASE shop` 再 `USE shop`。
+没选库时只有"限定名"语句能跑（`SELECT * FROM shop.items`），裸表名（`SELECT * FROM items`）会报
+`no database selected`——先把库选上。
+
+    CREATE USER alice IDENTIFIED BY 'secret';    -- 普通账号，口令是明文，服务端加盐派生
+    ALTER USER alice IDENTIFIED BY 'new-secret'; -- 改口令
+    DROP USER alice;
+
+`CREATE USER` / `ALTER USER` / `DROP USER` 只有管理员能执行（Web 端在 SQL 控制台，命令行直接跑）。
+
+权限按**角色**给，三句话：
+
+    CREATE ROLE analyst;                        -- 建角色（平的角色，不可继承）
+    GRANT SELECT, INSERT ON orders TO analyst;  -- 授权：对象可以是表名或 *
+    GRANT analyst TO alice;                     -- 把角色给账号
+    REVOKE INSERT ON orders FROM analyst;       -- 收回权限
+    REVOKE analyst FROM alice;                  -- 收回角色
+    DROP ROLE analyst;
+
+| 权限 | 覆盖 |
+| ---- | ---- |
+| `SELECT` | `SELECT`（含 JOIN、投影、`WHERE` 里的子查询） |
+| `INSERT` | `INSERT`（含 `VALUES` 里的子查询） |
+| `UPDATE` | `UPDATE`（含赋值与 `WHERE` 里的子查询） |
+| `DELETE` | `DELETE`（含 `WHERE` 里的子查询） |
+| `ALL` | 上面四种，等价于逐条授权 |
+
+- 对象写 `*` 表示当前库里所有表；写表名时按**当前库**限定（在 `sales` 库执行 `GRANT ... ON orders`
+  授权的是 `sales.orders`），换库要重新授权。
+- 管理员（root）隐式拥有全部权限，不用授权；DDL（建表、建索引等）一律只有管理员能做。
+- 角色语句本身只有管理员能跑；普通账号跑 `\dr` / `GET /api/roles` 会被拒（`administrator required`）。
+- 授权变更立即生效；已经登录的会话不会被踢下线。
+- 当前限制：没有列级授权，没有 `WITH GRANT OPTION`，角色不可继承，也没有自助查询（普通账号不能自己
+  看自己的授权，得问管理员）。
+
+Web 端对应的接口是 `/api/roles` 系列（`GET` 列表、`POST` 建角色、`DELETE /api/roles/:name` 删角色、
+`POST/DELETE /api/roles/:name/grants` 授权/收权、`POST/DELETE /api/roles/:name/members[/:user]` 成员），
+全部管理员专属。
+
+## `chusql-web` 选项
+
+    chusql-web [options]
+
+| 选项 | 对应配置键 | 默认 |
+| ---- | ---------- | ---- |
+| `--config FILE` | — | 固定位置的 `chusql.toml` |
+| `--host H` | `[web] host` | `127.0.0.1` |
+| `--port N` | `[web] port` | `7777` |
+| `--static DIR` | `[web] static_dir` | `static` |
+| `--user NAME` | `[web] user` | `root` |
+| `--storage SERVER` | `[web] storage_server` | — |
+| `--cookie-secure BOOL` | `[web] cookie_secure` | `false` |
+| `--body-limit N` | `[web] body_limit` | `65536` |
+| `--session-idle N` | `[web] session_idle` | `28800` |
+| `--session-max N` | `[web] session_max` | `86400` |
+| `--login-max-attempts N` | `[web] login_max_attempts` | `5` |
+| `--login-window N` | `[web] login_window` | `300` |
+| `--page-size N` | `[web] rows_per_page` | `25` |
+| `--max-page-size N` | `[web] max_page_size` | `500` |
+| `--max-rows N` | `[web] max_rows` | `1000` |
+| `--max-sql-length N` | `[web] max_sql_length` | `20000` |
+| `--seed BOOL` | `[web] seed` | `false` |
+| `-h, --help` | — | 帮助 |
+
+REST 接口（界面的一键操作全走结构化接口）：
+
+| 分组 | 接口 |
+| ---- | ---- |
+| 探活（无需登录） | `GET /api/health`、`GET /api/status` |
+| 会话 | `POST /api/login`、`POST /api/logout`、`GET /api/session` |
+| 设置 | `GET`/`PUT /api/settings`、`GET`/`PUT /api/ui-settings` |
+| 库 | `GET`/`POST /api/databases`、`DELETE /api/databases/:name` |
+| 表 | `GET`/`POST /api/tables`、`GET`/`DELETE /api/tables/:t` |
+| 行 | `GET`/`POST /api/tables/:t/rows`、`PATCH`/`DELETE /api/tables/:t/rows/:id` |
+| 索引与列 | `POST /api/tables/:t/indexes`、`DELETE /api/tables/:t/indexes/:col`、`DELETE /api/tables/:t/columns/:col` |
+| 演示数据 | `POST /api/demo-data` |
+| SQL 控制台 | `POST /api/query`（`CREATE USER` / `CREATE ROLE` / `GRANT` 也在这里跑） |
+| 角色 | `GET`/`POST /api/roles`、`DELETE /api/roles/:name`、`POST`/`DELETE /api/roles/:name/grants`、`POST`/`DELETE /api/roles/:name/members[/:user]` |
+
+除探活、登录和首页（`GET /`、`GET /static/:file`）外都要带会话 Cookie。选库用 `X-ChuSQL-Database` 头：
+**不带这个头就是"没选库"**，此时只有限定名语句（`db.table`）能跑，裸表名会得到 400 `no_database`；
+`GET /api/databases` 和 `POST`/`DELETE /api/databases/:name` 不需要选库。普通身份碰 `system` 库一律 403。