云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载导读Olares 默认会给社区应用分配一串由数字与字母组成的随机 route ID访问地址形如https://7e89d2a1.laresprime.olares.com既不美观也难以记忆。本文以官方手册 custom-app-domain.md 为核心完整讲解两种改造访问入口的方案——自定义 route ID三级域名前缀与自定义域名第三方 FQDN前者只需在设置界面填写一个前缀即可立即生效后者则涉及 HTTPS 证书、CNAME 记录与异步校验。文中会以 Jellyfin 为例逐步演示操作并结合仓库前端源码ApplicationDomain.vue与 CLI 实现domain.go解释每一步背后的原理与约束帮助你彻底掌握 Olares 应用入口的可访问性配置。背景知识route ID 与入口Entrance的概念在开始配置前先理解 Olares 应用访问地址的结构。根据 network.md每个 Olares 应用可以拥有一个或多个入口Entrance每个入口对应一个访问点其典型 URL 格式为https://{routeID}.{domain}其中route ID是标识具体应用或应用入口的唯一标识。系统应用使用预定义、便于记忆的 route ID例如desktop、market社区应用则默认使用8 位随机字符串 入口索引从 0 开始例如应用 route ID 为92d76a13、含两个入口时第一个入口为92d76a130访问地址为92d76a130.bob.olares.com。domain由你的 Olares ID 派生例如 Olares IDalice123olares.com对应alice123.olares.com。换句话说所谓自定义 route ID在技术上就是为你的 Olares 域名{username}.olares.com额外增加一个三级子域前缀而自定义域名则是把某个完整 FQDN如media.n1.monster绑定到某个应用入口上。两种个性化方式速览方式产物是否需要 DNS 记录是否需要 HTTPS 证书是否支持 Olares 认证自定义 route IDhttps://jellyfin.laresprime.olares.com否平台托管 DNS 与 TLS否是沿用原认证策略自定义域名https://media.n1.monster是CNAME 记录是用户提供 PEM 证书与 RSA 私钥否仅支持Public认证级别两种方式并非互斥设置自定义 route ID 后旧 URL 依然可用新 URL 是https://prefix.zone设置自定义域名后原 Olares URL 与自定义域名两个地址同时有效。前提条件要使用自定义域名你需要提前准备一个你拥有控制权的已注册域名。该域名的 DNS 设置权限用于创建CNAME 记录。一个有效的HTTPS 证书及其 RSA 私钥格式为 PEM证书与私钥文本应以-----BEGIN-----开头、以-----END-----结尾。自定义 route ID 则不需要上述任何外部资源。设置自定义 route ID以 Jellyfin 为例route ID 是 Olares 应用 URL 中标识应用的那部分例如https://7e89d2a1.laresprime.olares.com中的7e89d2a1。默认情况下Olares 给社区应用分配的是数字与字母混合的随机 route ID难以记忆。设置自定义 route ID 的步骤如下⚠️注意route ID 必须唯一在同一 Olares 账户下自定义 route ID 不得与另一应用入口的默认或自定义 route ID 重复。如果修改 route ID 后应用 URL 返回404请参考 Custom route ID prevents app access 排查。在 Olares 上打开Settings进入ApplicationJellyfin。在Entrances下点击Jellyfin入口。在Endpoint settings中点击Set custom route ID旁的添加按钮。输入一个更易记忆、更具辨识度的 route ID例如jellyfin。点击Confirm确认。完成之后Jellyfin 即可通过以下两个地址访问原地址https://7e89d2a1.laresprime.olares.com新地址https://jellyfin.laresprime.olares.com原理与实现细节从源码角度自定义 route ID 对应的是前端页面 ApplicationDomain.vue 中的third_level_domain字段third-level domain 即三级域对应 UI 中的 custom route ID。提交时调用 store 中的setupDomain通过POST /api/applications/{app}/{entrance}/setup/domain接口将配置写入见 application.ts。值得注意的约束保留前缀auth、desktop、wizard是保留前缀不可用作自定义 route ID。唯一性前缀在同一用户 zone 内不得重复也不能与应用的默认域名冲突。冲突由写入本身拒绝无需预先检查提交时若冲突会直接报错。这些规则可以从 CLI 的校验逻辑与诊断工具中印证olares-cli doctor thirdleveldomain见 thirdleveldomain.go会审计每个用户 zone 内的third_level_domain冲突报告duplicate重复与reserved保留字两类问题。设置自定义域名以 Jellyfin 为例⚠️警告自定义域名会关闭 Olares 认证使用自定义域名的应用不支持 Olares 认证。只有将入口的Authentication level设置为Public的应用入口才能配置自定义域名。你可以为单个应用分配自定义域名。若希望在整个 Olares 中所有服务统一使用同一个自定义域名则需要在激活设备之前于 Olares Space 中完成设置具体参见 Set up a custom domain for your Olares。以下示例将 Jellyfin 的访问地址从https://7e89d2a1.laresprime.olares.com改为https://media.n1.monster在 Olares 上打开Settings进入ApplicationJellyfin。在Entrances下点击Jellyfin入口。在Access policies下将Authentication level设置为Public点击Submit提交更改。在Endpoint settings中点击Set custom domain旁的添加按钮。在弹出的Set custom domain对话框中输入你的自定义域名并粘贴有效的 HTTPS 证书与私钥。两个文件都必须以-----BEGIN-----行开头、以-----END-----行结尾。点击Confirm提交。点击Activation按钮打开激活说明弹窗。按照弹窗中的说明到域名注册商处添加一条 CNAME 记录。在本示例中添加一条Name为media、Value为laresprime.olares.com的 CNAME 记录。点击Confirm关闭激活弹窗。此时自定义域名状态应显示 Wait for CNAME to be activated等待 CNAME 激活。DNS 传播通常需要几分钟到几小时具体取决于你的域名注册商。一旦 CNAME 记录被校验通过自定义域名状态会自动更新为 Activated已激活。此后Jellyfin 可通过以下两个地址访问原 Olares URLhttps://7e89d2a1.laresprime.olares.com自定义域名https://media.n1.monster状态流转与校验原理自定义域名的激活不是一个提交即生效的过程而是包含 CNAME 记录与证书异步校验的五阶段流水线。CLI 文档 domain.go 中对此有精确描述cname_target自定义域名需要指向的 CNAME 目标——即Olares zone如laresprime.olares.com注意它不是应用的当前 URL务必以系统返回的值为准。cname_target_statusunset/set表示是否已提交 domain finish它并不代表平台已检测到 CNAME。cname_statusunset/pending/active/cert-not-found/cert-invalid/timeout/error表示平台异步校验的最终结果。整个流程可以用下表概括阶段判定依据下一步动作未开始third_party_domain为空确认入口认证级别为public等待 DNS已设置域名cname_target_status为空或unset将cname_target原样告知用户配置 CNAME不要提前执行 finish激活中cname_target_statussetcname_statuspending轮询domain get无需其他操作完成cname_statusactive通过 HTTPS 确认访问证书问题cname_statuscert-not-found/cert-invalid重新检查 PEM 证书对再次domain set长时间 pendingcname_statuspending超过注册商 TTL对比真实 DNS 记录与cname_target修正后重新 finish校验放弃cname_statustimeout偶见error同样对比记录若记录无误则视为平台侧问题从 application.ts 的 store 实现看前端界面的每次操作都对应一个后端接口getDomainSetup→GET /api/applications/{app}/{entrance}/setup/domain读取当前配置与状态setupDomain→POST /api/applications/{app}/{entrance}/setup/domain写入 route ID / 自定义域名 / 证书 / 私钥setupCName即界面上的 Activation 按钮→GET /api/applications/{app}/{entrance}/setup/domain/finish标记 CNAME 已配置触发平台侧校验CLI 方式用 olares-cli 完成同样的配置除了 Settings 界面Olares CLI 也提供了完整的入口域名管理命令。对于自动化运维或无法访问界面的场景这是一个更精确、可脚本化的替代方案。基础命令结构如下# 查看某个应用所有入口的域名配置 olares-cli settings apps domain list app # 查看单个入口的当前配置含 cname_target / cname_status 等状态 olares-cli settings apps domain get app entrance # 写入配置读-改-写语义未指定的字段保持不变 olares-cli settings apps domain set app entrance [flags] # 确认第三方 CNAME 已配置触发异步校验 olares-cli settings apps domain finish app entrancePipeline A自定义 route ID对应 UI 的 custom route IDolares-cli settings apps domain set app entrance --third-level jellyfin执行后立即生效新地址为https://jellyfin.zone。此流程不需要 CNAME、不需要 finish等待应用恢复running状态后通过 HTTPS 验证新 URL 即可。Pipeline B自定义域名第三方 FQDN# 1. 先将认证级别设为 public自定义域名不支持 Olares 认证 olares-cli settings apps auth-level set app entrance --level public # 2. 注册域名并同时提交证书对 olares-cli settings apps domain set app entrance \ --third-party media.example.com \ --cert-file ./fullchain.pem \ --key-file ./privkey.pem # 3. 读取 cname_target将 CNAME 记录交给开发者/管理员配置 olares-cli settings apps domain get app entrance # 4. 确认记录已存在后再执行 finish olares-cli settings apps domain finish app entrance # 5. 轮询直到 cname_status 变为 active olares-cli settings apps domain get app entrancedomain set的可用参数如下参数说明--third-level prefix设置三级域前缀自定义 route ID如foo对应foo.userdomain--clear-third-level清除三级域前缀--third-party fqdn设置第三方自定义域名完整 FQDN--clear-third-party清除自定义域名连同证书与私钥--cert-file path读取 PEM 证书文件设置--third-party时必填除非使用--clear-third-party--key-file path读取 PEM 私钥文件设置--third-party时必填除非使用--clear-third-party注意domain set采用**读-改-写read-modify-write**语义只传--third-level不会清空已有的第三方域名配置反之亦然要显式删除某一维度必须使用--clear-third-level/--clear-third-party。该语义在 domain.go 的runDomainSetWithDoer中有完整实现。约束与注意事项以下约束同时适用于界面操作与 CLI 操作理解它们有助于避免最常见的配置失败自定义域名必须搭配 Public 认证级别。入口为private时写入会被拒绝错误信息custom domain can not be set when auth level is privateinternal入口无法从互联网访问同样无法使用自定义域名。证书与私钥必须是 RSA、PEM 格式且可被读取。--cert-file/--key-file从磁盘原样读取因此位于 root 专属目录通常是/etc/letsencrypt/live/...的 PEM 文件需要复制而不是移动以免影响证书续期到私有临时目录私钥副本保持0600权限并在domain set返回后删除。证书一般使用完整证书链。Certbot 默认签发 ECDSA 证书需显式指定--key-type rsa。Certbot 默认产出的私钥是 PKCS#8 格式的 ECDSA而平台校验器假定 PKCS#8 即为 RSA这会导致不可读的失败。签发时务必加上--key-type rsa。域名必须为完整 FQDN。example.com、media.example.com均可单独的标签bare label或带尾点trailing-dot的形式会在存储前被拒绝。入口级配置逐个入口处理。域名配置是针对单个入口的一个应用若含多个入口需要为每个需要独立主机名的入口重复整个流程。常见问题排查Q1修改自定义 route ID 后应用 URL 返回 404这通常是 route ID 冲突所致。ts-custom-route-domain.md见 文档给出了完整排查流程判断条件问题发生在添加/修改自定义 route ID 或 Olares 重启之后某个应用 URL 返回404或多个不相关的应用 URL 同时失效同一 Olares 账户下两个应用入口被分配了相同的自定义 route ID。原因自定义 route ID 会成为用户 Olares 域名下的一个子域必须在使用该域名的应用入口间保持唯一。若受影响版本接受了重复值生成的网关配置中会出现同一主机名多次网关无法加载该路由配置波及范围可能超过冲突的两个应用本身。解决若还能通过其他可用的 Olares URL 进入 Settings则找到引起问题的 route ID在SettingsApplications中选中占用重复 route ID 的应用在Entrances下打开受影响入口于Endpoint settings中移除该自定义 route ID 或改为唯一值提交后再访问原应用 URL。注意 route ID 比较时不区分大小写新建时不要复用其他应用的默认 route ID 或自定义 route ID。若 Settings 也无法访问不要照搬其他用户支持案例中的 Kubernetes patch 命令应用资源名包含账户与安装相关的特定值改错资源可能影响应用数据或其他用户。应记录 Olares 版本、被修改 route ID 的应用与入口、自定义 route ID必要时脱敏个人信息、受影响范围单个应用还是全部 URL、具体 HTTP 状态码/浏览器报错及开始时间通过私密渠道联系 Olares 支持处理。Q2cname_status一直停留在pending原因通常是 CNAME 记录缺失、仍在传播或指向了错误的目标。重新执行domain get读取cname_target与 DNS 面板中实际持有的记录值对比修正。注意finish本身不做 DNS 校验——它只把cname_target_status置为set、cname_status置为pending并触发平台校验当平台查询结果为空或出错时会放弃本轮且不写回任何状态入口会一直停留在pending。因此建议以开发者确认记录已存在作为执行finish的前提并通过经过的时间超过注册商 TTL来判断是否出了问题。Q3提交证书时报证书无效cname_status为cert-not-found或cert-invalid时说明问题出在证书而非 DNS。请检查PEM 是否以-----BEGIN-----开头并以-----END-----结尾私钥是否为 RSA而非 ECDSA是否使用了完整证书链。修正后重新执行domain set提交即可。延伸阅读Olares 网络架构概念入口、端点、route ID为整个 Olares 设置统一自定义域名Olares Space 流程自定义 route ID 导致应用无法访问的排查应用域名配置前端实现应用域名配置 CLI 实现与状态机route ID 冲突诊断工具赞分享云原生后端运维【免费下载链接】TerminusOpen-Source Personal Cloud OS for Always-On Agents项目地址https://gitcode.com/gh_mirrors/terminus2/Terminus点击查看免费下载相关推荐自定义路由 ID 冲突导致 Olares 应用 URL 返回 404诊断、修复与预防自定义路由 ID 冲突导致 Olares 应用 URL 返回 404诊断、修复与预防 本文是 OlaresTerminus 开源个人云操作系统应用访问故障云原生后端运维Chalice 自定义域名配置完全指南为 REST 与 WebSocket API 绑定专属域名Chalice 自定义域名配置完全指南为 REST 与 WebSocket API 绑定专属域名 Chalice 支持为部署的 REST API 与 WebS后端云原生免费把 GIMP 3.0 变成 Photoshop 手感PhotoGIMP 三步迁移教程免费把 GIMP 3.0 变成 Photoshop 手感PhotoGIMP 三步迁移教程 如果你也经历过这种时刻Photoshop 的月费又涨了你打开 G创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考