Olares 高级设置实战：仓库镜像源管理、镜像查看与系统日志导出

• 云原生
• 后端
• 运维

在 Olares 的设置 > 高级页面中，集中提供了与系统运行维护相关的三类能力：管理软件仓库镜像源、查看已下载的应用与系统镜像、导出系统日志。本文以 Olares 官方中文手册《管理仓库和镜像》为主线，结合 Terminus 仓库（Olares 的开源个人云操作系统）前后端源码，深入讲解每个功能的使用步骤、底层实现原理与 API 调用链，帮助你理解镜像下载加速机制，并在遇到问题时快速导出诊断日志。

功能总览：设置中的"高级"页面

在 Olares 桌面端打开设置，进入高级，可以看到一个面向开发与运维的系统管理入口集合，主要包括：

• 仓库管理：查看 Olares 用于下载系统镜像和软件包的源仓库，并配置镜像端点以优化下载速度和稳定性；
• 镜像管理：查看 Olares 系统上下载和缓存的所有应用及软件包镜像，支持按仓库筛选与关键词搜索；
• 导出系统日志：手动收集系统组件运行日志并打包下载，用于故障排查；
• 系统环境变量：配置系统级环境变量（如第三方 API 密钥），具体操作参见设置系统级环境变量。

从前端路由结构看，上述能力集中在apps/packages/app/src/pages/settings/Developer/目录下，对应MirrorPage.vue（仓库管理）、MirrorEndpointPage.vue（镜像站管理）、MirrorImagesPage.vue（镜像管理）、LogPage.vue（导出系统日志）等页面组件，由统一的状态管理 storeapps/packages/app/src/stores/settings/mirror.ts封装所有镜像相关 API 请求。

管理仓库：查看源仓库与镜像占用

仓库管理页面允许你查看 Olares 用于下载系统镜像和软件包的源仓库，同时可以进入单个仓库配置其镜像端点。

查看仓库列表

操作步骤：

1. 前往设置>高级>仓库管理；
2. 在仓库列表中查看每个仓库的名称、相关镜像数量和镜像大小。

前端实现细节：MirrorPage.vue中表格列定义与官方界面完全对应——Repo name（仓库名称）、Image count（镜像数量）、Image size（镜像大小，通过format.humanStorageSize格式化为人类可读的单位），末尾的操作列提供进入镜像站管理页的入口按钮。移动端则使用卡片网格布局展示相同字段。若系统未使用任何镜像仓库，页面会显示"未使用任何镜像仓库"空状态提示。

后端聚合逻辑：该列表并非直接读取配置文件，而是由olaresd守护进程动态合并而来。daemon/pkg/containerd/registry.go中的ListRegistries做了两步聚合：

1. 读取所有已配置镜像端点（/etc/containerd/certs.d/下各 registry 命名空间的hosts.toml）生成仓库条目；
2. 通过 CRI 接口列出本地缓存的所有镜像（daemon/pkg/containerd/api.go的ListImages），用containerd/reference解析每个镜像 tag 的 Hostname，统计每个仓库的image_count（镜像数量）与image_size（镜像大小总和，单位字节）。

这意味着"镜像数量/大小"反映的是该仓库相关的本地缓存镜像的实时统计，前端在拿到数据后还会按镜像大小降序排序展示（见mirror.ts的getRegistryMirrors）。

管理仓库镜像：配置与排序镜像端点

为仓库配置镜像端点（Mirror Endpoint）可以显著提高镜像拉取的速度和稳定性——当从主仓库拉取缓慢或失败时，Olares 会按优先级依次尝试镜像端点。

操作步骤

1. 在仓库管理页面，找到目标仓库，然后在操作列点击展开按钮（右箭头图标）；
2. 进入镜像站管理页面后，你可以执行以下三类操作：

• 重新排序镜像端点：点击上移（置顶）或下移（置底）图标调整顺序。Olares 会优先使用列表中排名靠前的端点；
• 删除不再需要的端点：点击删除图标，确认后移除该镜像源；
• 添加新的镜像端点：点击添加镜像站，输入镜像站 URL，然后点击确认。

排序与删除的前端逻辑（MirrorEndpointPage.vue）：页面先通过getRegistryEndpoint(registry)拉取当前端点的有序列表；排序操作本质上是"从数组中取出目标项、再插入到队首/队尾"，删除则是过滤掉该项，最后统一调用putRegistryEndpoint(registry, items)将新列表整体写回服务端。添加时若端点已存在则直接提示成功并跳过重复写入。

底层原理：containerd certs.d 与 hosts.toml

镜像端点的持久化并不依赖数据库，而是直接写入 containerd 的镜像仓库配置文件。daemon/pkg/containerd/registry.go对此有清晰说明：

• 配置文件采用 containerdconfig v3 的config_path机制，路径为/etc/containerd/certs.d/<registry>/hosts.toml，每个子目录对应一个 registry 命名空间（例如docker.io）；
• 写入镜像端点无需重启 containerd，因为hosts.toml在每次拉取镜像时都会被重新读取（handler_containerd.go头部注释明确说明这一点）。

写文件时（writeRegistryMirror），端点按传入顺序写入，排名靠前者优先：

server = "https://registry-1.docker.io" [host."https://mirror.example.com"] capabilities = ["pull", "resolve"]

其中server是上游仓库的规范地址：对于docker.io会特殊映射为https://registry-1.docker.io（因为 docker.io 本身不提供/v2API，拉取实际由 registry-1 提供），其他仓库则为https://<registry>。每个[host."<url>"]表声明pull、resolve两种 capability，表示该端点可用于拉取与解析镜像。

值得注意的实现细节是优先级恢复：TOML 的 table 在数据模型上是无序的，parseHostsTOMLMirrors借鉴 containerd 自身 resolver 的做法，按每个 host 表在文件中的源码行号排序，从而还原出用户在界面上排定的优先级顺序。当端点列表被删空时，hosts.toml文件会被整体移除，让 containerd 回落到默认解析逻辑。

端点校验：新增端点时服务端会调用normalizeEndpoint做校验——去除首尾空白、要求非空、必须能被解析为带 host 的 URL，且协议只能是http或https，否则返回 400 错误并在前端弹出失败提示。

对应的 API 调用链

后端对应实现位于 handler_containerd.go，路由注册与鉴权逻辑见 containerd_group.go。请求头携带X-Signature（设备标识）用于鉴权。

管理镜像：筛选与搜索本地缓存镜像

镜像管理页面提供了 Olares 系统上下载和缓存的所有应用及软件包镜像的全面视图，你可以通过筛选或搜索快速定位特定镜像。

使用方式

页面顶部提供两个筛选工具：

• 下拉框（按仓库筛选）：默认选项为"全部"；页面加载时会从镜像列表中提取所有出现过的仓库名（取repo_tags[0]中/分隔的第一段作为仓库标识）动态生成筛选选项；
• 搜索框：按镜像名称关键词实时过滤。

列表按镜像名称和镜像大小两列展示，镜像名取自镜像 tag（repo_tags），会去掉仓库前缀并保留/之后的路径部分。移动端则以卡片形式展示仓库名与镜像大小。

数据来源

MirrorImagesPage.vue通过mirrorStore.getRegistryImages()拉取数据，最终调用GET /api/containerd/images?registry=<registry>。后端ListImages（api.go）通过 containerd CRI 图像服务列出全部镜像，若传了registry参数则用reference.Parse解析每个 tag 的 Hostname 做精确过滤。数据结构定义在 types.go 与 mirror.ts：

export interface RegistryImage { id: string; // 镜像 ID size: number; // 镜像大小（字节） repo_tags: string[]; // 镜像标签列表 }

前端还会过滤掉没有repo_tags的镜像，并按 tag 去掉仓库前缀后的路径进行字典序排序，保证列表稳定可读。仓库列表页的镜像数量列也支持点击跳转到该仓库的镜像管理页（enterImages路由跳转）。

补充说明：镜像管理页中的"清除镜像"（Clean up images）功能在前端代码中当前处于注释禁用状态（MirrorImagesPage.vue中相关按钮与deleteImagesPrune调用被注释），但其后端能力PruneImages（POST /api/containerd/images/prune）已实现：它会跳过被Pinned标记的镜像以及 tag 中包含pause的沙箱关键镜像，仅清理未被容器引用的镜像，并返回删除数量与释放空间。

导出系统日志：为故障排查收集诊断信息

系统日志记录了系统组件的运行状态，是故障排除的关键诊断信息。当遇到异常时，你可以手动导出日志文件，并将其附加到支持工单或 GitHub Issue 中，帮助 Olares 团队更快定位问题。

手动导出步骤

1. 前往设置>高级>导出系统日志；
2. 点击收集生成日志文件。收集完成后，日志文件会显示在收集历史中，并保存到Home/pod_logs/目录；
3. 在收集历史中，点击已生成日志文件旁的打开，打开日志目录；
4. 右键单击该日志文件，然后选择下载。

以上步骤来自仓库中的可复用文档片段 export-system-logs.md。

前端交互细节

LogPage.vue的实现体现了完整的异步任务交互：

• 点击收集后调用terminusDStore.collect_logs()，同时将页面状态切换为"收集中"（带旋转加载动画）；
• 随后每 3 秒轮询一次系统状态（setInterval+system_status()），读取olaresInfo.collectingLogsState判断收集是否完成或失败，失败时展示collectingLogsError原因；
• 收集完成后，页面显示日志保存路径/Home/pod_logs，点击打开会跳转到 Files 应用的http://<host>/Files/Home/pod_logs/目录（将 URL 中的settings子域替换为files）。

后端编排机制

日志收集是多节点集群级操作，由olaresd的 master 侧编排实现（collect_logs/cmd.go）：

• 请求进入后先做同步鉴权（authorize），校验调用者身份与作用域，越权访问直接返回 403；
• 收集任务按runID注册到内存任务表（tasks.go，最多跟踪 50 条、超出后淘汰最旧记录），返回后即可通过状态接口查询进度，且多个收集任务可并发执行；
• master 通过 fanout 机制把任务分发到每个就绪节点的本地执行端点/command/collect-logs-node，每个节点只收集本节点的局部日志；
• 各节点结果汇总后在调用者自己的 Home 目录（JuiceFS 后端、多节点可见）下合并为单一归档文件，并chown回 Olares 用户（UID/GID 1000），确保用户在 Files 中可直接打开下载；
• 单节点收集调用超时上限为 15 分钟（nodeCollectTimeout），足以覆盖大型 host/pod 日志包。

状态接口由 handler_collect_logs_status.go 提供，按runID返回 in-progress / completed / failed 三种状态以及每节点结果，日志归档的压缩与打包逻辑见 archive.go。

自动收集日志的替代方式

除了手动导出，你也可以在以下场景自动收集并上报日志：

• 在 Ticket 应用中，展开系统日志并选择采集日志，日志会随工单自动提交；
• 在 Olares Space 中，使用olares-cli命令自动上传日志并创建工单。

小结

通过设置 > 高级中的三个页面，Olares 将系统维护的关键操作收敛为可视化入口：

• 仓库管理 + 镜像站管理：基于 containerd certs.d 的hosts.toml机制动态管理镜像端点，无需重启运行时即可生效，端点优先级通过文件行号可靠恢复，是优化镜像拉取速度与稳定性的首选手段；
• 镜像管理：通过 CRI 接口实时聚合本地镜像缓存视图，按仓库筛选与关键词搜索，方便排查镜像占用与版本问题；
• 导出系统日志：由 master 节点编排、fanout 到每个节点收集并合并归档到Home/pod_logs/，配合 Ticket 应用或 Olares Space 的olares-cli可自动随工单上报。

若需要更深入的实现细节，可直接阅读仓库中的对应源码：前端状态管理、前端页面组件、containerd 镜像端点实现、镜像列表与清理实现以及日志收集编排实现。

• 云原生
• 后端
• 运维