Dozzle 默认配置文件（`__default__`）实战：预置用户界面设置并理解其读写机制

Dozzle 默认配置文件__default__实战预置用户界面设置并理解其读写机制【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzleDozzle 把每个用户的界面偏好主题、语言、置顶容器、折叠分组、可见的 JSON 键等持久化在磁盘的/data/username/profile.json中并在未启用认证或用户尚无个人配置时回退到一个名为__default__的特殊配置文件。本文以 Dozzle 官方文档中的 Default Profile 章节为主体完整继承其文件位置、JSON 示例与全部可用设置项说明并结合仓库源码internal/profile、internal/web、前端profileStoragecomposable还原配置的读取与写入调用链读完后你可以为团队部署预置一份开箱即用的界面配置并理解每条设置最终落在哪个文件、经过哪些代码路径。背景按用户存储的界面偏好与__default__回退Dozzle 会把每个用户的界面偏好持久化到磁盘上的/data/username/profile.json。当认证被禁用时或者任何用户尚未登录并自定义过设置时Dozzle 都会回退到这个名为__default__的特殊配置文件。你可以通过创建/data/__default__/profile.json来分发一份预配置好的配置文件。匿名访客以及任何还没有保存过配置的新用户在首次访问时都会加载这份设置。从源码结构看这个回退逻辑在后端入口中体现得非常直接。__default__是硬编码的常量页面渲染时若请求上下文中没有已认证用户就取该常量作为档案用户名internal/profile/disk.go 中定义profileFilename profile.json和DefaultUsername __default__internal/web/index.go 在渲染首页模板时执行profileUsername : profile.DefaultUsername仅当user ! nil时才改用user.Username随后调用profile.Load并把结果注入页面模板的Config.profile。也就是说__default__身份既是新访客的模板也是未启用认证部署中匿名用户的活动配置文件——同一份文件身兼二职。文件位置与创建方式配置文件位于/data/__default__/profile.json如果该文件不存在Dozzle 会使用内置默认值启动。只有当你想要覆盖这些默认值时才需要创建它。关于/data目录internal/profile/disk.go 的init()函数在进程启动时会将其解析为当前工作目录下的绝对路径filepath.Abs(./data)若目录不存在则以0755权限自动创建。在 Docker 部署中这个目录通常就是挂载的卷因此只要把预置文件放进挂载卷的__default__子目录即可。完整示例所有字段可选下面是官方文档给出的完整示例。注意所有字段都是可选的只需写入你希望覆盖的项。{ settings: { showTimestamp: true, showStd: false, showAllContainers: false, softWrap: true, collapseNav: false, smallerScrollbars: false, search: false, compact: false, menuWidth: 15, size: medium, lightTheme: auto, hourStyle: auto, dateLocale: auto, locale: en, groupContainers: at-least-2, automaticRedirect: delayed }, pinned: [], visibleKeys: [], collapsedGroups: [] }可用设置项一览settings对象支持以下字段与 docs/guide/default-profile.md 的表格一致字段类型说明showTimestampboolean在每条日志行旁显示时间戳showStdboolean显示 stdout/stderr 流指示器showAllContainersboolean在侧边栏中包含已停止的容器softWrapboolean长日志行自动换行而非横向滚动collapseNavboolean以折叠的侧边栏状态启动smallerScrollbarsboolean使用更细的滚动条searchboolean默认启用内联搜索compactboolean紧凑的日志行距menuWidthnumber侧边栏宽度占窗口宽度的百分比上限为50sizestring字号small、medium、largelightThemestring主题偏好auto、light、darkhourStylestring时间格式auto、12、24dateLocalestring日期/时间格式auto、en-US、en-GB、de-DE、en-CAlocalestring界面语言如en、fr、degroupContainersstring侧边栏分组always、at-least-2、neverautomaticRedirectstring跳转到新容器instant、delayed、none集合之外的取值不会被接受因此groupContainers: stack或dateLocale为fr-FR都不会产生你预期的效果。这一点在前端类型定义中有明确印证assets/stores/settings.ts 将size、lightTheme、hourStyle、dateLocale、automaticRedirect、groupContainers声明为字面量联合类型如small | medium | large超出集合的值在合并默认值时不会被采纳。该文件中的取值同时决定了前端内置默认值与预置配置的优先级关系。assets/stores/settings.ts 定义了DEFAULT_SETTINGS例如search: true、softWrap: true、menuWidth: 15、groupContainers: at-least-2、automaticRedirect: delayed前端通过mergeDefaults: true将服务器档案中存在的字段合并到默认值之上——这正是“所有字段可选”能够成立的机制基础。源码中的额外字段从 internal/profile/disk.go 的Settings结构体看后端实际还接受两个未列入上表的字段编写预置文件时可以一并利用collapseCloudRailboolean折叠云端侧栏highlightErrors*bool指针 omitempty日志错误高亮。源码注释特别说明它采用指针是为了让旧版本写出的档案保持“静默”避免注入一个false覆盖前端默认值true。此外 assets/stores/settings.ts 前端类型中还包含showImageUpdateAlert、showAppIcons、terminalFontSize等字段它们同样会随档案同步保存但官方文档未把它们列入推荐预置项按需使用即可。顶层字段置顶容器、可见键与折叠分组顶层字段pinned、visibleKeys、collapsedGroups接受数组允许你为首访用户预先置顶容器或预先折叠分组pinned字符串数组容器 ID 列表visibleKeys任意 JSON 数组控制 JSON 日志中默认可见的键collapsedGroups字符串数组侧边栏中默认折叠的分组名。Dozzle 还会在顶层写入releaseSeen、dismissedImageUpdates和dismissedLinkHint用于记住用户已经关闭过的提示。若预置dismissedLinkHint: true则所有用户的初次启动都不会再看到容器链接提示。对照 internal/profile/disk.go 的Profile结构体顶层字段与 JSON 标签的完整映射为settings对象omitempty、pinned字符串数组反序列化时若为nil会被补成空数组见 Load、visibleKeys、releaseSeen、collapsedGroups、dismissedImageUpdates、dismissedLinkHint以及一个用于跨浏览器同步“最近告警已读”时间戳的lastSeenAlertTsint64纳秒。工作原理完整的读写调用链官方文档总结的三条行为在仓库中都能找到一一对应的实现1. 页面加载时读取档案。首页请求进入 internal/web/index.go先确定档案用户名已认证用户取user.Username否则profile.DefaultUsername再调用profile.Load。Loadinternal/profile/disk.go读取dataPath/username/profile.json文件不存在时返回errMissingProfileErr此时前端会退回到内置默认值渲染界面。2. 界面修改时写回自己的档案。前端所有偏好都通过 assets/composable/app/profileStorage.ts 的useProfileStorage管理一旦config.user存在或authProvider为none就会对该键启用深度 watcher并在值变化时向/api/profile发起PATCH见 profileStorage.ts。路由注册在 internal/web/routes.go处理函数 internal/web/profile.go 同样先以profile.DefaultUsername起步、再按认证用户覆盖用户名最后调用profile.UpdateFromReader。3.__default__的双重角色。当认证关闭时读写两端都落在__default__上因此它既是新访客的模板也是匿名用户的活动档案——这与文档“既作为模板、又作为活动配置文件”的结论一致。值得注意的实现细节是UpdateFromReaderinternal/profile/disk.go采用**“先加载、再合并解码”**的策略它先把已有档案Load出来再把请求体 JSON 解码进这个已有结构体然后整体保存。这意味着前端按单个键增量PATCH时其余键会原样保留而不是被整体覆盖若加载旧档案失败非“文件不存在”类错误则记录日志后以空档案继续。安全与部署注意事项路径穿越防护safePath 用filepath.Base校验用户名任何包含路径分隔符或目录穿越.、..的用户名都会被errInvalidUsername拒绝保证档案文件只能落在/data的第一级子目录内。并发写入写入由包级互斥锁mux串行化save通过utils.WriteFile落盘目录以0755权限按需创建。只读挂载技巧如果只想分发默认值、但仍允许匿名用户在运行时个性化调整可以把/data/__default__/profile.json以只读方式挂载——Dozzle 将无法持久化变更前端会记录同步失败日志但界面功能不受影响。这是官方文档给出的推荐做法。小结预置 Dozzle 界面配置的路径非常短在数据卷中创建/data/__default__/profile.json只写需要覆盖的字段其余交给内置默认值与前端mergeDefaults合并逻辑兜底。理解上面梳理的Load读取与PATCH /api/profile→UpdateFromReader合并写入两条链路后你可以准确预期三种场景的行为——匿名部署一切读写都落在__default__、启用认证后新用户首访读取__default__模板、首次修改即分叉到个人档案、以及只读挂载场景模板只读、界面继续可用。相关文档可继续参考 docs/guide/authentication.md 了解认证与用户档案的关系。【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考