CasaOS 0.4.15 配置参数详解

目标：系统梳理 CasaOS v0.4.15 的配置文件体系（/etc/casaos/ 下 7 个配置文件 + 启动钩子），逐项解释每个参数的含义、默认值与修改影响，并给出端口修改、商店源管理等高频配置的实测验证过程。全部配置内容与命令回显已在 Ubuntu 22.04.5 LTS 环境实测采集。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• CasaOS 版本：v0.4.15（组件：casaos v0.4.15 / gateway v0.4.9-alpha4 / message-bus v0.4.4-3-alpha2 / user-service v0.4.8 / local-storage v0.4.4 / app-management v0.4.10-alpha2 / casaos-cli v0.4.4-3-alpha1 / rclone v1.61.1）
• 配置目录：/etc/casaos/（安装时生成，每个配置文件均附带同名 .sample 模板）
• 数据目录：/var/lib/casaos/；日志目录：/var/log/casaos/；运行时目录：/var/run/casaos/
• WebUI 端口：80（casaos-gateway 监听）
• 服务托管：systemd（casaos、casaos-gateway、casaos-message-bus、casaos-user-service、casaos-local-storage、casaos-app-management、rclone 共 7 个服务）

二、前置条件

• 已按《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》完成 CasaOS 安装并能访问 WebUI。
• 具有 root 权限（/etc/casaos/ 下文件属主为 root，读写需要 root）。
• 理解配置生效机制：所有配置在服务启动时读取，修改后必须重启对应服务才能生效；网关端口等关键项改错会导致 WebUI 不可达，改前先备份。

三、参数查看与修改方式

3.1 查看配置清单

ls -la /etc/casaos/

实测回显：

total 68
drwxr-xr-x 3 root root 4096 Oct 21 07:02 .
drwxr-xr-x 1 root root 4096 Oct 21 07:02 ..
-rw-r--r-- 1 root root  338 Oct 21 07:02 app-management.conf
-rw-r--r-- 1 root root  338 Oct 21 07:02 app-management.conf.sample
-rw-r--r-- 1 root root  455 Oct 21 07:02 casaos.conf
-rw-r--r-- 1 root root  455 Oct 21 07:02 casaos.conf.sample
-rw-r--r-- 1 root root   24 Oct 21 07:02 env
-rw-r--r-- 1 root root  115 Oct 21 07:02 gateway.ini
-rw-r-- 1 root root   54 Oct 21 07:02 gateway.ini.sample
-rw-r--r-- 1 root root  214 Oct 21 07:02 local-storage.conf
-rw-r-- 1 root root  214 Oct 21 07:02 local-storage.conf.sample
-rw-r--r-- 1 root root  107 Oct 21 07:02 message-bus.conf
-rw-r-- 1 root root  107 Oct 21 07:02 message-bus.conf.sample
drwxr-xr-x 2 root root  4096 Oct 21 07:02 start.d
-rw-r--r-- 1 root root  177 Oct 21 07:02 user-service.conf
-rw-r--r-- 1 root root  177 Oct 21 07:02 user-service.conf.sample

解读：7 个功能文件 + 6 个 .sample 模板（env 无模板）+ start.d/ 启动钩子目录。.sample 是安装器生成的出厂模板，修改主文件前可对照它确认原始值。

3.2 查看服务读取哪个配置

每个服务的 systemd 单元写明了配置路径，以主服务为例：

systemctl cat casaos --no-pager

实测回显：

# /lib/systemd/system/casaos.service
[Unit]
After=casaos-message-bus.service
After=rclone.service
Description=CasaOS Main Service

[Service]
ExecStart=/usr/bin/casaos -c /etc/casaos/casaos.conf
PIDFile=/var/run/casaos/casaos.pid
Restart=always
Type=notify

[Install]
WantedBy=multi-user.target

解读：主服务通过 -c 显式指定 /etc/casaos/casaos.conf；其余服务按约定读取同目录下各自的 .conf（如 casaos-gateway 读 gateway.ini）。

3.3 修改参数的标准流程

cp /etc/casaos/<配置文件> /etc/casaos/<配置文件>.bak   # 1. 备份
vim /etc/casaos/<配置文件>                            # 2. 修改
systemctl restart <对应服务>                          # 3. 重启生效
systemctl is-active <对应服务>                        # 4. 验证

⚠️ 主服务每次重启会更换监听端口并由网关动态注册，systemctl restart casaos 后网关自动跟随；单独重启其他服务不影响主服务注册关系。

四、参数总览

关键差异解读：casaos.conf 管主服务自身行为，gateway.ini 管对外入口，其余四个 .conf 是各后端微服务的同名职责配置；多数参数保持默认即可，实际高频改动集中在 gateway.ini 的 port、local-storage.conf 的 USB/mergerFS 开关与 app-management.conf 的商店源 三处。

五、核心参数分类详解

5.1 主服务配置 casaos.conf

主服务承载系统信息、文件管理、通知等核心 API，配置分 [app]（应用与存储路径）、[server]（运行模式与外部服务）、[system]（预留段）三段。实测完整内容：

[app]
PAGE_SIZE = 10
RuntimeRootPath = runtime/
LogPath = /var/log/casaos/
LogSaveName = log
LogFileExt = log
DateStrFormat = 20060102
DateTimeFormat = 2006-01-02 15:04:05
TimeFormat = 15:04:05
DateFormat = 2006-01-02
DBPath     = /var/lib/casaos
ShellPath  = /usr/share/casaos/shell
UserDataPath = /var/lib/casaos/conf

[server]
RunMode = release
ServerApi = https://api.casaos.io/casaos-api
Handshake = socket.casaos.io
Token =
USBAutoMount =

[system]

逐项说明：

💡 说明：Go 程序的时间格式模板以固定基准时间表示（如 2006-01-02 15:04:05），修改时保持语法形态，不要写成普通 strftime 格式。

5.2 网关配置 gateway.ini

网关是唯一对外入口，配置最关键的是监听端口。实测完整内容：

[common]
runtimepath=/var/run/casaos

[gateway]
logfileext=log
logpath=/var/log/casaos
logsavename=gateway
port=80

逐项说明：

端口修改的完整实测过程（含验证与还原）见《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》第七章：修改 port=8080 并 systemctl restart casaos-gateway 后，ss -ltn 确认监听 *:8080、curl 返回 HTTP 200；改回后监听恢复 *:80。

5.3 消息总线配置 message-bus.conf

消息总线承载组件间事件分发（应用安装进度、磁盘插拔等）。实测完整内容：

[common]
RuntimePath=/var/run/casaos

[app]
LogPath=/var/log/casaos
LogSaveName=message-bus
LogFileExt=log

逐项说明：RuntimePath 是总线运行时目录（含其 SQLite 库 message-bus.db）；LogPath/LogSaveName/LogFileExt 组合出总线日志文件 /var/log/casaos/message-bus.log。三段路径参数均无性能语义，仅在把日志/运行时迁移到独立分区时需要改。

5.4 用户服务配置 user-service.conf

用户服务负责账户与认证。实测完整内容：

[common]
RuntimePath=/var/run/casaos

[app]
LogPath = /var/log/casaos
LogSaveName = user-service
LogFileExt = log
DBPath     = /var/lib/casaos/db
UserDataPath = /var/lib/casaos

逐项说明：

未登录时调用用户接口可看到认证保护生效（实测回显）：

curl -s http://127.0.0.1/v1/users/info

{"success":401,"message":"token is invalid","data":null}

5.5 本地存储配置 local-storage.conf

存储服务管理磁盘发现、挂载与 USB。实测完整内容：

[common]
RuntimePath=/var/run/casaos

[app]
LogPath=/var/log/casaos
LogSaveName=local-storage
LogFileExt=log
DBPath=/var/lib/casaos/db
ShellPath=/usr/share/casaos/shell

[server]
USBAutoMount=
EnableMergerFS=false

逐项说明：

💡 技术拓展：多盘合并存储不止 mergerFS 一种方案，常见对比如下——

方案	原理/特点	适用场景
mergerFS	用户态联合挂载，按策略分布文件，单盘损坏只丢该盘	家庭 NAS 聚合异构磁盘（CasaOS 内置方案）
LVM	块设备级卷管理，可条带/镜像	需要快照与弹性扩容
ZFS/Btrfs	文件系统级池化，带校验与快照	数据完整性要求高
RAID（mdadm）	块级冗余/条带	硬件级冗余需求

CasaOS 实际内置 mergerFS（安装时附带 /usr/local/bin/mergerfs.ctl），因为其"逐文件分布、异构盘友好、损坏影响局部化"的特性最贴合家庭存储场景。

5.6 应用管理配置 app-management.conf

应用管理服务负责 Docker 应用生命周期与应用商店。实测完整内容：

[common]
RuntimePath = /var/run/casaos

[app]
LogPath = /var/log/casaos/
LogSaveName = app-management
LogFileExt = log
AppStorePath = /var/lib/casaos/appstore
AppsPath = /var/lib/casaos/apps

[server]
appstore = https://casaos.app/store/main.zip
appstore = https://github.com/bigbeartechworld/big-bear-casaos/archive/refs/heads/master.zip

逐项说明：

实测通过 CLI 查看当前生效的商店源列表：

casaos-cli app-management list app-stores

实测回显：

ID   URL                                                                                 STORE ROOT
--   ---                                                                                 ----------
0    https://casaos.app/store/main.zip                                                   /var/lib/casaos/appstore/casaos.app/4e6bf64b187e30664ab8e6ed48331e96/build/sysroot/var/lib/casaos/appstore/default.new
1    https://github.com/bigbeartechworld/big-bear-casaos/archive/refs/heads/master.zip   /var/lib/casaos/appstore/github.com/2a1238d53212bfce4e8f861dcb8ef3fe/big-bear-casaos-master

解读：STORE ROOT 即每个源解包后的落地路径；官方源在 appstore/casaos.app/<hash>/ 下，社区源在 appstore/github.com/<hash>/ 下，缓存损坏时删除对应目录后重新注册即可。

5.7 环境变量文件 env

实测完整内容：

OPENAI_API_KEY=sk-xxxxxx

该文件为主服务 AI 相关功能提供密钥注入点，格式为标准 KEY=VALUE。默认值为占位 sk-xxxxxx（未配置状态），接入自有 OpenAI 兼容服务时替换为真实 Key。⚠️ 该文件含敏感凭据，权限应保持 rw-r--r-- 以内并避免提交到版本库；本文档中的 sk-xxxxxx 为出厂占位值而非真实密钥。

5.8 启动钩子目录 start.d/

/etc/casaos/start.d/ 下的可执行脚本会在主服务启动流程末尾自动执行（实测目录内容）：

-rwxr-xr-x 1 root root  559 Oct 21 07:02 register-ui-events.sh

出厂仅含 register-ui-events.sh（注册 UI 事件订阅）。把自定义脚本放入该目录并赋予执行权限，即可在主服务每次启动后自动执行（如清理任务、通知钩子）。实测主服务日志中可见钩子执行记录：

Executing post-start script /etc/casaos/start.d/register-ui-events.sh using /bin/sh
Finished executing post-start scripts.

六、生产配置模板

以下模板面向 4GB 内存 / SATA SSD / 家庭轻负载（10 个以内应用） 的典型家庭云主机，改动仅限高频项，其余保持默认：

# /etc/casaos/gateway.ini —— 对外端口改到 8080（避开 80 上的既有 Web 服务或反代）
[gateway]
port=8080

# /etc/casaos/local-storage.conf —— 开启 USB 自动挂载
[server]
USBAutoMount=ON
EnableMergerFS=false

# /etc/casaos/casaos.conf —— 离线/内网环境减少不必要外联
[server]
ServerApi =
Handshake =

逐项说明：port=8080 后 WebUI 访问地址变为 http://<服务器IP>:8080，注意同步防火墙放行；USBAutoMount=ON 便于外接备份盘即插即用；ServerApi/Handshake 置空可让主服务跳过对官方在线服务的依赖（版本检查改为手动），完全离线的家庭服务器建议采用。修改后逐个重启对应服务并验证：

systemctl restart casaos-gateway
systemctl restart casaos-local-storage
systemctl restart casaos

验证（端口已迁移到 8080 时）：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8080/

实测回显：

HTTP 200

七、常见问题（FAQ）

Q1：改了配置不生效？ 配置在服务启动时读取，改完必须重启对应服务（网关改端口重启 casaos-gateway，主服务参数重启 casaos）。重启后用 systemctl is-active <服务> 确认 active，再用对应功能验证（如 ss -ltn 看端口）。

Q2：配置改错导致 WebUI 打不开？ 先 ss -ltnp | grep -E ':80 |:8080' 确认网关监听是否还在；若网关未监听，用备份恢复：cp /etc/casaos/gateway.ini.bak /etc/casaos/gateway.ini && systemctl restart casaos-gateway。仍不通时查 /var/log/casaos/gateway.log 与 journalctl -u casaos-gateway -n 50。

Q3：应用商店列表显示 "internal error - store root not found"？ 该状态出现在商店缓存目录与索引不一致时（实测在重装/恢复后出现）。处理：casaos-cli app-management unregister app-store <id> 注销失效源，再用 casaos-cli app-management register app-store <url> 重新注册，注册为异步执行（回显 trying to register app store asynchronously - see /var/log/casaos/app-management.log for any errors.），进度与错误看 app-management.log。

Q4：日志文件在哪，能轮转吗？ 全部在 /var/log/casaos/：log.log（主服务）、gateway.log、message-bus.log、user-service.log、local-storage.log、app-management.log。CasaOS 不自带轮转，可接入系统 logrotate 配置对该目录按大小轮转。

Q5：想迁移整个 CasaOS 到新磁盘？ 配置在 /etc/casaos、数据在 /var/lib/casaos、日志在 /var/log/casaos，三处目录整体迁移后重启全部 casaos* 服务即可；/var/run/casaos 为运行时目录无需迁移（重启自动重建）。

八、参考链接

1. CasaOS 主仓库与各组件仓库：https://github.com/IceWhaleTech/CasaOS
2. 官方 Wiki（配置与排障）：https://wiki.casaos.io/en/troubleshooting
3. 本专栏相关文档：《CasaOS 介绍与选型指南》《Ubuntu 22.04 安装 CasaOS 0.4.15 指南》《CasaOS 0.4.15 常用 CLI 命令与工具详解》