Crafty Controller 4.11.0 配置参数详解

目标：把 Crafty Controller 4.11.0 的配置面讲透——config.json 全部 34 个顶层参数逐项含义/默认值/改动影响、数据库侧设置（crafty_settings 表）、日志与证书文件，并给生产配置模板。本文以 Docker Compose 在跑实例（4.11.0，Ubuntu 24.04.5 宿主）为对象，全部取值与回显为 2026-11-02 实测。

一、环境信息

二、前置条件

面板已按部署篇起栈并处于运行态；以下命令均在 compose 目录执行：

$ docker compose -f docker-compose.yml ps
 Container crafty-4.11.0-panel Running

# 直接读宿主侧配置文件（bind mount，与容器内同一文件）
$ head -8 docker/config/config.json
{
    "allow_nsfw_profile_pictures": false,
    "base_url": "localhost:8443",
    "big_bucket_repo": "https://jars.arcadiatech.org",
    "cookie_expire": 30,
    "crafty_logs_delete_after_days": 0,
    "delete_default_json": false,
    "dir_size_poll_freq_minutes": 5,

三、参数查看与修改方式

Crafty 的配置分两层：

1. 文件层 config.json——面板全局参数（本文主体）。查看：Web 设置页 Server Config，或 cat 文件。修改：官方推荐走 Web 设置页（即时写回文件并生效）；直接改文件则重启容器后生效——实测把 virtual_terminal_lines 由 70 改 71 后静置 75 秒，日志无任何重载动作；重启后启动序列出现配置检查行：

$ docker compose -f docker-compose.yml restart
 Container crafty-4.11.0-panel Restarting 
 Container crafty-4.11.0-panel Started

$ docker logs crafty-4.11.0-panel --since 1m | grep 'remote changes'
[+] Crafty: 11/02/26 22:43:59 - INFO:	Checking for remote changes to config.json

2. 数据库层 crafty_settings 表——密钥与个性化设置，只走 Web UI，不在 config.json 里。实测表结构与取值（敏感值截断展示）：

crafty_settings cols: ['id', 'secret_api_key', 'login_photo', 'login_opacity', 'master_server_dir',
'cookie_secret', 'og_enabled', 'og_title', 'og_description', 'og_image', 'og_color', 'logo_full', 'logo_square']
crafty_settings row: (1, 'WJ61…(48位随机Key)', 'login_1.jpg', 100, '/crafty/servers', 'FCS9…(32位随机)',
1, '', '', '', '#005cd1', '', '')

要点：secret_api_key/cookie_secret 是首启随机生成的系统级密钥（API 签名与会话 Cookie 签名），文档与备份中按敏感值对待；master_server_dir 即服务器实例根目录（对应挂载卷 /crafty/servers）；og_*/logo_*/login_* 是 Open Graph 嵌入、品牌图标与登录页背景等外观项。

⚠️ 注意：config.json 由 Web UI 整体重写，手工排版/键序不保证保留；JSON 本身不支持注释，请勿在文件里加注释（会导致解析失败）。

四、参数总览

实测在跑实例的 config.json 全文（34 个顶层参数，2030 字节）：

{
    "allow_nsfw_profile_pictures": false,
    "base_url": "localhost:8443",
    "big_bucket_repo": "https://jars.arcadiatech.org",
    "cookie_expire": 30,
    "crafty_logs_delete_after_days": 0,
    "delete_default_json": false,
    "dir_size_poll_freq_minutes": 5,
    "disabled_language_files": [],
    "enable_otp_skew": false,
    "enable_passkey_auth": false,
    "enable_user_self_delete": false,
    "experimental": false,
    "general_user_log_access": false,
    "history_max_age": 7,
    "https_port": 8443,
    "keywords": [
        "help",
        "chunk"
    ],
    "language": "en_EN",
    "max_audit_entries": 300,
    "max_image_upload_size_mb": 5,
    "max_log_lines": 700,
    "max_login_attempts": 3,
    "monitored_mounts": "/crafty/backups",
    "passkey_rp_name": "Crafty Controller",
    "reset_secrets_on_next_boot": false,
    "sampling_fallback_divisor": 12,
    "sampling_tiers": [
        {
            "max_hours": 6,
            "sample_rate": 1
        },
        {
            "max_hours": 24,
            "sample_rate": 2
        },
        {
            "max_hours": 72,
            "sample_rate": 6
        }
    ],
    "show_contribute_link": true,
    "show_errors": true,
    "silent_notif_fields": [
        "dashboard_columns",
        "server_order"
    ],
    "stats_update_frequency_seconds": 30,
    "superMFA": false,
    "time_range_presets": [
        {
            "hours": 1,
            "label": "Last Hour"
        },
        {
            "hours": 3,
            "label": "Last 3 Hours"
        },
        {
            "hours": 6,
            "label": "Last 6 Hours"
        },
        {
            "hours": 12,
            "label": "Last 12 Hours"
        },
        {
            "hours": 24,
            "label": "Last 24 Hours"
        },
        {
            "hours": 48,
            "label": "Last 2 Days"
        },
        {
            "hours": 168,
            "label": "Last 7 Days"
        }
    ],
    "trusted_proxies": [],
    "virtual_terminal_lines": 70
}

速查表（默认值即出厂/实测值）：

五、核心参数分类详解

5.1 网络与访问

• base_url（localhost:8443）：面板生成回调、资源链接、WebSocket 目标时用的对外地址。出厂值指向本机，从外网访问必改成 域名或IP:端口，否则登录后的实时推送/跳转仍打回 localhost。实测本环境经宿主 8135 映射访问，浏览器侧功能正常的前提是面板可见地址与访问地址一致（反代场景见 trusted_proxies）。
• https_port（8443）：Tornado 监听端口，实测启动回显 Starting Web Server on ports https:8443 → https://10.89.62.2:8443 is up and ready for connections.。改此值必须与 compose 的 ports 映射同步改，两处只改其一即失联。
• trusted_proxies（[]）：可信反向代理地址/CIDR 列表。空=不信任任何前置，面板只认直连源 IP；置于 Nginx/Traefik 后需把代理网段填进来，否则审计与限流里的来源全是代理 IP。
• cookie_expire（30）：登录会话 Cookie 有效天数。30 天偏宽松，公共/共享主机建议降到 7 以内。

5.2 认证与安全

• max_login_attempts（3）：连续失败锁定阈值，出厂即保守（3 次），配合面板自身锁定期使用。
• superMFA（false）：置 true 后强制所有用户启用两步验证（TOTP/Passkey），用户未绑定 MFA 会被引导拦截。
• enable_passkey_auth / passkey_rp_name（false / Crafty Controller）：4.11 线 WebAuthn 口令免登能力（DB 侧 passkey_data/passkey_challenges 表实测存在）。开启后面板作为 WebAuthn Relying Party，passkey_rp_name 是展示给用户认证器的 RP 可读名；域名化部署时该值与 base_url 域一致性影响 passkey 可用性。
• enable_otp_skew（false）：TOTP 校验是否放宽时间窗（容忍前后一个周期）。客户端与服务端时钟漂移大时可开，代价是重放窗口变宽。
• general_user_log_access（false）：普通（非管理员）用户能否读面板/服务器日志。默认关闭是正确安全姿态。
• enable_user_self_delete（false）：允许用户在个人设置自助删除账号。
• delete_default_json（false）：首次登录成功后是否自动删除 default.json 预置口令文件。实测本实例该文件仍存在（-rw-rw-r-- 1 root root 56 ... default.json），与默认值一致；生产建议置 true 或手工删除，避免预置口令长期留在配置卷。
• reset_secrets_on_next_boot（false）：置 true 后下次启动轮换 cookie_secret 与 secret_api_key（全员会话失效、旧 API Key 签名作废），完成即自动回写 false。实测启动日志对应动作：Checking for reset secret flag → No flag found. Secrets are staying。

5.3 日志与终端

• max_log_lines（700）：Web 端一次拉取 MC 服务器日志的行数上限，控制大日志页渲染开销。
• virtual_terminal_lines（70）：控制台虚拟终端环形缓冲行数——终端里能往上滚的历史深度。
• crafty_logs_delete_after_days（0）：面板自身日志（logs/ 下 commander.log/audit.log/auth_tracker.log）自动清理天数，0=永不自动删。实测 daemon 模式下 commander.log 为 0 字节（主日志走容器 stdout），长期运行需靠容器日志驱动限额兜底。
• keywords（["help","chunk"]）：日志/终端高亮关键词，命中词在 Web 终端标色，便于扫异常。
• history_max_age（7）：指标历史（host_stats/server_stats）保留天数，直接决定 SQLite 体积增长。
• max_audit_entries（300）：审计日志保留条数上限（audit 用 JSON formatter 落 audit.log）。

5.4 指标与采样

• stats_update_frequency_seconds（30）：APScheduler 指标采集周期。实测回显两处印证：Stats collection frequency set to 30 seconds 与调度器 Running job "Stats.record_stats (trigger: interval[0:00:30], ...)" executed successfully。服多、宿主弱可放宽到 60。
• sampling_tiers（6h×1 / 24h×2 / 72h×6）：查询图表时按时间窗分档降采样——查最近 6 小时取全量点，24 小时取 1/2，72 小时取 1/6；超出全部档位用 sampling_fallback_divisor（12）即 1/12 抽稀。
• dir_size_poll_freq_minutes（5）：每 5 分钟统计一次各服务器目录体积（磁盘占用列）。
• monitored_mounts（/crafty/backups）：磁盘容量监控的挂载点清单（逗号分隔多个）。只监控备份卷是出厂默认，把 /crafty/servers 加进来更能在世界膨胀前报警。
• time_range_presets（7 档：1/3/6/12/24/48/168 小时）：仪表盘时间窗快捷按钮，纯展示层配置。

💡 技术拓展：时序降采样常见三策略——

策略	原理	取舍
固定保留期+原始精度	到期整段删除	实现最简单，长周期查询失真或超慢
分档降采样（Crafty 采用）	时间越远抽稀比越大	近期精确、远期趋势，查询代价平稳
预聚合连续汇总（如 Prometheus recording rules）	定期物化 avg/max 等聚合	最省查询，需额外聚合管道

Crafty 无独立 TSDB，SQLite 单表 + 查询侧分档抽样（tiers+fallback）是"零依赖"定位下的合理取舍。

5.5 界面与语言

• language（en_EN）/ disabled_language_files（[]）：界面语言与禁用的语言包文件列表（裁剪语言资源时填）。
• show_errors（true）：UI 直接展示错误详情（含堆栈线索）。对内开无妨，对外暴露实例建议关。
• show_contribute_link（true）：页脚贡献链接。
• silent_notif_fields（["dashboard_columns","server_order"]）：这两类个人偏好字段变更不触发跨端通知去重提示（纯 UI 噪音抑制）。
• allow_nsfw_profile_pictures（false）：头像上传不做 NSFW 判定时放行与否，默认拦截。
• max_image_upload_size_mb（5）：图片上传（头像/图标/登录背景）体积上限。

5.6 下载源与实验特性

• big_bucket_repo（https://jars.arcadiatech.org）：BigBucket 服务器核心清单源。面板启动即探活并缓存清单到 config/bigbucket.json，实测健康回显：

INFO:app.classes.big_bucket.bigbucket:Big bucket is alive and responding as expected
DEBUG:urllib3.connectionpool:https://jars.arcadiatech.org:443 "GET /manifest.json HTTP/1.1" 200 57109
INFO:app.classes.big_bucket.bigbucket:Manual refresh completed.

缓存实测 118355 字节，mc_java_servers/vanilla 类目覆盖 26.3、1.21.11 等版本，每条含 piston-data.mojang.com 官方 URL 与 sha256。受限网络可改自建镜像地址或预置缓存文件（超时排障见部署篇 FAQ 10.3）。

• experimental（false）：实验特性总开关，开启后暴露未完成功能入口，生产勿动。

六、生产配置模板

适用场景：16GB 内存 / NVMe SSD / 单机 5 个以内 MC 服 / Nginx 反代 + 正式域名。相对出厂值的改动项（其余保持默认）：

{
    "base_url": "crafty.example.com",
    "trusted_proxies": ["10.89.62.0/24"],
    "cookie_expire": 7,
    "superMFA": true,
    "enable_passkey_auth": true,
    "delete_default_json": true,
    "show_errors": false,
    "stats_update_frequency_seconds": 60,
    "history_max_age": 14,
    "crafty_logs_delete_after_days": 30,
    "monitored_mounts": "/crafty/backups,/crafty/servers"
}

逐条理由：base_url 落真实域名（WebSocket/回调正确性）；trusted_proxies 填反代网段取真实客户端 IP；cookie_expire 30→7 收紧会话；superMFA+passkey 双因子强推（4.11 已内置 passkey 表）；delete_default_json 防预置口令残留；show_errors 关闭防信息泄露；采样 30→60 秒降 SQLite 写入；history_max_age 7→14 天保两周趋势；面板日志 30 天自动清；磁盘监控加 servers 卷防世界膨胀爆盘。改完执行 docker compose -f docker-compose.yml restart 生效（实测回显见第三章）。

七、常见问题

7.1 改了 config.json 没反应

实测文件修改后 75 秒内无热加载迹象，必须重启容器（docker compose restart，启动序列会打印 Checking for remote changes to config.json）；或直接在 Web 设置页修改（即时写回并生效）。

7.2 外网访问后仪表盘转圈/连不上实时数据

base_url 还是出厂 localhost:8443，前端按它拼 WebSocket/资源地址。改成实际访问的域名:端口后重启。

7.3 反代后面板日志里全是代理机 IP

trusted_proxies 为空。把反代所在网段加入后重启，面板才会采信 X-Forwarded-For。

7.4 想改 HTTPS 端口

https_port（config.json）与 compose ports 映射两处同步改；只改容器内端口而宿主映射不动，外部访问即 502/失联。

7.5 API Key 泄露/换密钥

置 reset_secrets_on_next_boot: true 并重启，cookie_secret 与 secret_api_key 轮换（全员下线、旧签名作废），随后确认回写 false。Key 的逐把管理在 Web 设置 → API Keys（表 api_keys 字段实测：token_id/name/created/user_id/server_permissions/crafty_permissions/full_access）。

7.6 启动日志报 Unable to read logging config from /crafty/app/config/logging.json

config 卷缺 logging.json 时的非致命告警（本实例实测出现过，面板照常起）。从同版本镜像取一份放入 config 卷即可（做法见部署篇 FAQ 10.2）；该文件是标准 Python dictConfig，定义 commander/tornado_access/schedule/auth/audit/cmd_queue 各日志器格式。

7.7 配置备份边界

需要备份的只有 config/ 目录整包（config.json、db/crafty.sqlite、web/certs、bigbucket.json、default-creds.txt）。其中 db/、default-creds.txt、secret_api_key/cookie_secret 属敏感件，备份包加密存放。

八、参考链接

• 官方文档（Settings 章节）：https://docs.craftycontrol.com
• 官方仓库（config 出厂件 app/config_original/）：https://gitlab.com/crafty-controller/crafty-4
• 部署与首启排障：《Crafty Controller Docker Compose 部署指南》
• 选型背景：《Crafty Controller 介绍与选型指南》