后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载本文是 PhotoPrism 项目中用于统一定义集群架构术语的权威文档 GLOSSARY.md 的深度解读。它面向参与 PhotoPrism 多实例集群Portal 控制平面 Instance 实例 Service 服务开发、部署与文档编写的工程师系统阐明instance、portal、node、tenant、Join Token、AdvertiseUrl、SiteUrl等核心概念的准确含义与使用边界。读完本文你将能够在集群配置、API 契约与文档中准确选用术语而不产生歧义理解节点注册/api/v1/cluster/nodes/register背后的术语体系并掌握术语变更的管理流程。一、GLOSSARY 的定位术语的唯一事实来源Single Source of TruthPhotoPrism 项目为集群功能维护了一份集中的术语表其定位在 GLOSSARY.md 的开篇部分明确为三点唯一事实来源它是整个 PhotoPrism 文档体系中术语用法的权威定义所有文档涉及的集群术语均以此为准。一次定义、全局复用术语在 GLOSSARY 中只定义一次其他文档直接引用本文件而不是在多个文档中各自重复定义、导致口径漂移。契约名称优先当技术/API 契约名称与面向用户的措辞不一致时必须保持契约名称不变例如 API 端点、字段名、环境变量名即内部叫什么就是什么外部措辞可以不同但契约字符串不能改。这一原则在源码中体现为角色、字段与端点名称以常量形式固化为契约例如acl.RoleInstance instance见 internal/auth/acl/const.go节点角色常量见 internal/service/cluster/roles.go。用户文档可以换措辞但这些字符串值在 API 与配置契约中保持稳定。二、权威术语详解Canonical TermsGLOSSARY 定义了 13 个核心术语按其语义可分为三类集群运行时角色、网络与标识、身份与路由归属。以下逐一结合仓库源码佐证。2.1 集群运行时角色admin、instance、portal、service、nodeadmin管理员— 拥有提升授权范围scopes或角色roles的用户或客户端。在 ACL 体系中portal角色拥有GrantFullAccess全量授权见 internal/auth/acl/grant.go而普通instance/service角色仅获得GrantSearchShared共享搜索权限事件通道上RolePortal也单独映射了全量授权见 internal/auth/acl/events.go。instance实例— 角色为instance的 PhotoPrism 运行时是集群中提供 UI/API/媒体功能的成员节点。它对应 ACL 常量RoleInstance instanceinternal/auth/acl/const.go。GLOSSARY 明确规定凡是描述集群运行行为与角色语义的地方一律使用instance/instances。从源码看它是节点注册时允许的两类角色之一另一个是service且是默认角色DefaultNodeRole cluster.RoleInstance见 internal/config/config_cluster.go。portal门户— 角色为portal的 PhotoPrism 运行时提供集群控制平面 API 与路由。它是集群的管理入口只有 portal 节点才能处理节点注册ClusterNodesRegister首先检查conf.Portal()非 portal 直接返回功能未启用见 internal/api/cluster_nodes_register.go、节点列表、节点更新与删除internal/api/cluster_nodes.go。Config.Portal()正是通过NodeRole() cluster.RolePortal判定internal/config/config_cluster.go且当运行Portal 版Edition时角色被强制固定为portalinternal/config/config_cluster.go。service服务— 角色为service的 PhotoPrism 运行时是非 instance 的集群成员专注于服务类工作负载例如 Ollama、Vision API 等模型服务。角色常量同样定义于 internal/service/cluster/roles.go。它不能充当 UI/媒体实例但在集群中具有独立身份与调用权限。node节点— 一个技术性标识符仅在 API/配置契约要求时使用例如端点/api/v1/cluster/nodes、字段NodeName、环境变量前缀PHOTOPRISM_NODE_*、配置路径config/node/...。GLOSSARY 的写作规则强调凡字段名、端点、标志/env 变量、配置路径或代码契约明确要求使用 node 的地方必须保留 node不得替换成 instance。源码中可见NodeConfigPath()返回config/node目录internal/config/config_cluster.go节点密钥文件位于config/node/secrets/如client_secret见 internal/config/config_cluster.goNodeName()返回[a-z0-9-]{1,32}格式的节点名internal/config/config_cluster.go注册端点对节点名的 DNS 标签语义做了严格校验小写字母、数字、连字符1–32 字符首尾必须为字母或数字internal/api/cluster_nodes_register.go。角色别名的归一化由NormalizeNodeRole实现internal/service/cluster/roles.goapp与instance均归一化为RoleInstanceportal、service各自映射无法识别的值返回空字符串。注意注册新节点时请求携带的角色仅限 instance 或 serviceportal 角色不会通过注册请求授予internal/api/cluster_nodes_register.go。2.2 网络与标识AdvertiseUrl、SiteUrl、cluster domain、cluster UUID、Join TokenAdvertiseUrl— 集群对等节点用于访问某个实例或服务的内部/服务 URL。它与面向浏览器的 SiteUrl 语义分离AdvertiseUrl 用于集群内节点间的路由调用。源码验证注册请求可携带AdvertiseUrl校验规则为绝对 URL、必须有 scheme 和 host允许 http/httpshttp 是为集群内部流量而允许的见 internal/api/cluster_nodes_register.go 与validateAdvertiseURLinternal/api/cluster_nodes_register.go。若请求未提供 AdvertiseUrlPortal 会依据ClusterDomain派生默认值https://name.domaininternal/api/cluster_nodes_register.go。节点侧Config.AdvertiseUrl()的优先级为显式配置 → 由ClusterDomain() NodeName()派生https://node.domain/→ 回退到SiteUrl()internal/config/config_cluster.go。SiteUrl— 实例的规范公共 URL/源origin。它是浏览器可访问的入口也是 OIDC issuer 的默认来源PortalOIDCIssuer()在未覆盖时回退到SiteUrl()见 internal/config/config_cluster.go。其校验比 AdvertiseUrl 更严格非本地域名必须使用 httpshttp 仅允许 loopbacklocalhost、127.0.0.1、::1或集群内部服务域名.svc、.local、.internal见validateSiteURLinternal/api/cluster_nodes_register.go。此外normalizeSiteURL还会将主机名小写化、限制总长度 255 字符internal/api/cluster_nodes_register.go。cluster domain集群域— 用于派生集群默认值的 DNS 域例如 Portal/实例 URL。Config.ClusterDomain()的解析顺序为显式配置小写化→ 从SiteUrl的主机名推导首个标签作为 NodeName、其余作为 ClusterDomain→ 从系统配置推导internal/config/config_cluster.go。Portal URL 支持变量替换如https://portal.${PHOTOPRISM_CLUSTER_DOMAIN}internal/config/config_cluster.go。cluster UUID— 用于配置与集群元数据的稳定集群标识符。Config.ClusterUUID()校验 UUID 格式rnd.IsUUID后返回internal/config/config_cluster.go。它会被写入每个注册响应供节点识别当前所属集群internal/api/cluster_nodes_register.go。Join Token— 用于初始注册的引导 Bearer 令牌对应端点POST /api/v1/cluster/nodes/register。这是新节点加入集群的入场券其语义边界非常严格令牌仅在Authorization: Bearer头中有效且用常数时间比较subtle.ConstantTimeCompare防止时序攻击internal/api/cluster_nodes_register.go。Join Token 绝不能用于修改已有节点注册若节点名已存在而请求携带有效 Join Token会被拒绝并返回 409 冲突internal/api/cluster_nodes_register.go已有节点的变更路径必须使用该节点自己的 OAuth 客户端令牌internal/api/cluster_nodes_register.go。新节点加入时Portal 会同时创建 OAuth 客户端、生成ClientSecret、并视RotateDatabase需求预配数据库凭据internal/api/cluster_nodes_register.go。令牌的生成与持久化由Config.JoinToken()/SaveJoinToken()完成支持内存配置、磁盘文件portal 节点存于config/portal/secrets/join_token普通节点存于config/node/secrets/join_token、懒生成并缓存internal/config/config_cluster.go。典型格式如k9sEFe6-A7gt6zqm-gY9gFh0。命令行可用photoprism cluster join-token生成令牌见 internal/commands/cluster_join_token.go注册命令的测试亦展示了--name pp-node-01 --role instance --join-token token的用法internal/commands/cluster_exit_codes_test.go。2.3 身份与路由归属client、app、tenantclient客户端— OAuth/API 客户端身份与凭据ClientID、ClientSecret广义上指任何 API 调用方。在集群场景中每个节点本身就是 Portal 注册表中一个 OAuth 客户端节点注册即创建客户端A join creates an OAuth clientinternal/api/cluster_nodes_register.go节点后续通过NodeClientID()/NodeClientSecret()参与集群鉴权internal/config/config_cluster.go。值得注意的是注册表与普通 OAuth 客户端共享同一命名空间internal/api/cluster_nodes_register.go因此节点名与普通客户端名不可冲突。app— 仅在名称/示例中作为有意标识符使用例如app.js、app.kubernetes.io/*、photoprism-app。GLOSSARY 特别强调app 不是首选的通用的运行时角色术语。这在源码中有直接呼应NormalizeNodeRole接受别名app但将其归一化为instanceinternal/service/cluster/roles.go以及 internal/auth/acl/roles.go 中app: RoleInstance的映射。也就是说历史/示例中出现的 app 指的就是实例正式契约值仍是instance。tenant租户— 共享域路由的所有权标签用于路径式 URL 如/i/tenant/...通常映射到已注册的实例名称。它与 instance 的分工是 GLOSSARY 写作规则的核心之一instance用于描述集群运行行为与角色语义tenant用于描述共享域路径归属与路由语义当术语出现歧义时回链到本 GLOSSARY 作为裁决依据。源码佐证可见于 OIDC 会话 Cookie 的清除路径逻辑当实例的 OIDC OP 为 Portal 时清除路径需要落在Portal 的共享域路径上而不是实例自身的/i/tenant基路径从而保证从任意节点都能执行集群级登出见 internal/api/oidc_session_cookie.go 及其测试 internal/api/oidc_session_cookie_test.go。三、写作规则何时用哪个词GLOSSARY 给出了四条可操作的选择规则可直接作为文档与代码注释的检查清单场景必须使用的术语原因描述集群运行时行为与角色语义instance / instances角色术语的规范表达描述共享域路径归属与路由语义tenant / tenants路由/归属标签映射已注册实例名字段名、端点、flag/env 变量、配置路径、代码契约明确要求node契约字符串必须保持不变仅作为有意标识符/示例app.js、app.kubernetes.io/*、photoprism-appapp不是通用运行时角色词术语出现歧义时回链/引用 GLOSSARY统一裁决这四条规则与本文第二节的源码证据完全一致契约层端点/api/v1/cluster/nodes、NodeName、config/node/...全部保留node运行时角色语义集群成员能力全部使用instance/portal/service共享域路由语义使用tenant/i/tenant路径app仅作为别名或示例标识符出现并在归一化时折叠为instance。四、术语变更管理Change ManagementGLOSSARY 明确了两条流程要求先改 GLOSSARY 再改别处当引入、重命名或澄清核心术语时必须先更新本文件使其始终处于先行位置避免文档体系先出现新词、术语表滞后。联动更新依赖文档术语一旦变更所有依赖文档必须同步修改以匹配新定义。这两条保证了整个 PhotoPrism 集群文档与代码注释的术语一致性也符合第一节唯一事实来源的总体定位——GLOSSARY 是术语治理的入口与裁决点。五、术语体系速查与源码索引以下将 13 个权威术语与仓库证据一一对应便于按需查阅术语一句话定义源码/路径证据admin拥有提升授权 scope/role 的用户或客户端internal/auth/acl/grant.goAdvertiseUrl集群对等节点访问实例/服务的内部 URLinternal/config/config_cluster.go、internal/api/cluster_nodes_register.goapp名称/示例中的有意标识符非通用角色词internal/service/cluster/roles.goclientOAuth/API 客户端身份与凭据ClientID/ClientSecretinternal/config/config_cluster.gocluster domain用于派生集群默认值的 DNS 域internal/config/config_cluster.gocluster UUID稳定集群标识符用于配置与元数据internal/config/config_cluster.goinstance角色为 instance、提供 UI/API/媒体功能的集群成员internal/auth/acl/const.go、internal/config/config_cluster.goJoin Token初始注册用的引导 Bearer 令牌POST /api/v1/cluster/nodes/registerinternal/config/config_cluster.go、internal/api/cluster_nodes_register.gonode契约层技术标识符端点/字段/环境变量/配置路径internal/api/cluster_nodes.go、internal/config/config_cluster.goportal角色为 portal、提供控制平面 API 与路由的运行时internal/config/config_cluster.go、internal/api/cluster_nodes_register.goservice角色为 service、专注服务工作负载的非实例成员internal/service/cluster/roles.goSiteUrl实例的规范公共 URL/originOIDC issuer 默认来源internal/config/config_cluster.go、internal/api/cluster_nodes_register.gotenant共享域路径归属标签/i/tenant/...映射已注册实例名internal/api/oidc_session_cookie.go六、结语GLOSSARY 虽短却是 PhotoPrism 集群功能在文档、API 契约与配置层保持术语一致性的基石。理解并遵守这套术语体系意味着在撰写集群相关文档时能准确区分运行时角色instance/portal/service与契约标识node、区分公共入口SiteUrl与集群内部路由AdvertiseUrl、以及理解共享域归属tenant的路径语义。对于希望深入集群实现的读者建议从 internal/api/cluster_nodes_register.go节点注册全流程与 internal/config/config_cluster.go集群配置解析两个文件继续追踪它们完整覆盖了本术语表中的大部分概念在实际代码中的落地形态。赞分享后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载相关推荐2025终极指南SQL Server命名规范与T-SQL编程风格权威实践2025终极指南SQL Server命名规范与T SQL编程风格权威实践 你是否还在为数据库对象命名混乱导致团队协作效率低下而烦恼是否因T SQL代码风格不functional-programming-jargon权威指南Fantasy Land规范中的核心术语functional programming jargon权威指南Fantasy Land规范中的核心术语 你是否在学习函数式编程时被各种晦涩术语困扰本文将文档知识库Apache Pulsar 2.0 核心变更指南Topic 命名规范、Tenant 重构与 Pulsar Functions 新特性Apache Pulsar 2.0 核心变更指南Topic 命名规范、Tenant 重构与 Pulsar Functions 新特性 Pulsar 2.0 是消息队列后端流处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考