6.4 KiB
配置选项
文件在哪
整条链路（数据库服务 / Web / 命令行）共用一份 chusql.toml，位置固定，没有环境变量可以覆盖：
| 平台 | 路径 |
|---|---|
| Windows | %APPDATA%\ChuSQL\chusql.toml（APPDATA 没设时退到相对路径 ChuSQL\chusql.toml） |
| Linux / macOS | $XDG_CONFIG_HOME/ChuSQL/chusql.toml，没设就是 ~/.config/ChuSQL/chusql.toml（HOME 也没有才退相对路径 ChuSQL/chusql.toml） |
安装脚本就是把 scripts/chusql.toml 这份模板写到上面的位置，并把安装时给的
user / password / data_dir 填进去。想临时读另一份文件，chusql-server、chusql-web、csql
都认 --config <path>（启动器 csql-web 没有选项，只读固定路径）。
优先级：命令行选项 > 配置文件 > 内置默认，也就是配置文件写什么，命令行随时能盖掉 （选项表见 commands.md）。
分区归属
| 分区 | 谁读 |
|---|---|
[page] [btree] [buffer] [storage] [log] |
存储层 chusql-core/storage（由 chusql-server 装入的动态库） |
[server] |
TCP 数据库服务 chusql-server（监听地址、端口、单行上限、结果行数上限） |
[web] |
Web 服务 chusql-web 与命令行 csql（账号、会话、限流、分页上限、静态目录） |
数据目录只有一份配置：chusql-server 读它来落盘，别的进程不碰。
存储的分区
| 键 | 默认 | 说明 |
|---|---|---|
[page] size |
4096 |
页大小（字节） |
[btree] order |
4 |
B+ 树阶 |
[buffer] pool_size |
1024 |
缓冲池页数 |
[storage] data_dir |
Windows %LOCALAPPDATA%\ChuSQL\data，Linux / macOS ${XDG_DATA_HOME:-~/.local/share}/chusql/data |
数据落哪（模板里那行是安装时替换的占位） |
[log] level |
info |
日志级别 |
数据目录跟着平台惯例走，跟安装脚本装的位置是同一处（Windows 装到 %LOCALAPPDATA%\ChuSQL、Unix 装到
~/.local/share/chusql，数据放在它下面的 data/）；LOCALAPPDATA/XDG_DATA_HOME/HOME 都没有时才退相对路径。
要固定就写绝对路径。
存储层没有自己的命令行选项：它是 chusql-server 进程内装入的动态库。
[web] 分区
| 键 | 命令行（chusql-web） |
默认 | 说明 |
|---|---|---|---|
host |
--host |
127.0.0.1 |
监听地址 |
port |
--port |
7778 |
监听端口 |
static_dir |
--static |
static |
静态资源目录（候选：给定值、static、chusql-web/static、../chusql-web/static、../static，取第一个存在的） |
user |
--user |
配置文件缺失时 root |
管理员账号名 |
password |
— | 文件里没有这一项时用内置演示口令 root / chusql |
管理员口令（明文，启动时哈希；见「口令与安全」） |
cookie_secure |
--cookie-secure |
false |
给会话 Cookie 加 Secure（HTTPS 部署时开） |
body_limit |
--body-limit |
65536 |
请求体上限（字节） |
session_idle |
--session-idle |
28800 |
会话空闲超时（秒） |
session_max |
--session-max |
86400 |
会话最大存活（秒） |
login_max_attempts |
--login-max-attempts |
5 |
连续失败几次后限流 |
login_window |
--login-window |
300 |
限流窗口（秒） |
rows_per_page |
--page-size |
25 |
默认每页行数 |
max_page_size |
--max-page-size |
500 |
每页行数上限 |
max_rows |
--max-rows |
1000 |
单次查询返回行数上限 |
max_sql_length |
--max-sql-length |
20000 |
SQL 字符数上限 |
seed |
--seed |
false |
库为空时灌演示数据 |
password_min_length |
— | 12 |
普通账号口令最短长度（允许 8–256） |
password_classes |
— | 2 |
口令至少包含几类字符（允许 1–4：小写/大写/数字/符号） |
键名两种写法都认
模板 scripts/chusql.toml 用下划线，Web 设置页写的是连字符（规范形式）。两种写法同时出现时连字符优先：
[web]
rows_per_page = 25 # 模板写法
rows-per-page = 50 # 设置页写法，生效
对应关系：static_dir→static-dir、session_idle→session-idle、session_max→session-max、
login_max_attempts→login-max-attempts、login_window→login-window、body_limit→body-limit、
rows_per_page→rows-per-page、max_page_size→max-page-size、max_rows→max-rows、
max_sql_length→max-sql-length、
password_min_length→password-min-length、password_classes→password-classes。
host、port、user、password、seed 只有一种写法。
[server] 分区
TCP 数据库服务 chusql-server 的监听参数。单独一段：别层的进程不认这一段，也不需要认。
| 键 | 命令行（chusql-server） |
默认 | 说明 |
|---|---|---|---|
host |
--host |
127.0.0.1 |
监听地址 |
port |
--port |
7777 |
监听端口；写 0 让系统分配，实际端口打在启动横幅里 |
max_message |
--max-message |
1048576 |
单行请求上限（字节），超了回 too_large |
max_rows |
--max-rows |
1000 |
单次查询返回行数上限，超了截断并置 truncated |
这四项改完要重启 chusql-server 才生效（Web 设置页也把它们标成需要重启）。
口令与安全
password给了明文 → 启动时哈希；显式留空（password = ""）＝ 只允许管理员免密登录，普通账号一律拒绝登录；- 整个文件里没有
password这一项 → 回落到内置演示口令root/chusql（仅用于本机试用，正式部署请写死）； - 普通账号由管理员在 SQL 控制台用
CREATE USER/ALTER USER/DROP USER管理，口令受password_min_length/password_classes约束； - 生产部署建议：
host = 127.0.0.1（或放在反向代理后）、cookie_secure = true、给管理员设口令， 并且别把数据目录放在共享盘上。
改配置的两种途径
- 直接编辑
chusql.toml（新值在下次启动生效）； - Web 设置页（
/api/settings）按分区把改动写回同一份文件——它会写成连字符形式。
每一项都带注释的模板在 scripts/chusql.toml。