Port：从服务目录建模到自助工作流治理
值班群里出现了一条数据库连接耗尽告警。接手的人知道服务名，却不知道代码仓库、Owner、上游调用方和回滚入口；仓库搜索得到三个同名项目，监控标签又使用另一套缩写。半小时后，真正的问题不是不会查日志，而是组织没有一张能回答“这个对象是谁、由谁负责、与谁相连、能对它执行什么动作”的可信地图。
Port 是商业 SaaS 开发者门户，没有供团队自行部署的开源门户控制面，也没有可固定的 SaaS“稳定版本号”。它把外部系统中的仓库、服务、部署、集群、告警和团队映射成统一目录，再把查询、质量标准和受控执行放到实体上下文中。启用入口是 EU 或 US 区域的 Port 租户和 Web 控制台；外部数据可以由 Port 托管的集成读取，也可以通过自托管 Ocean 集成从自己的网络主动推送。Ocean Framework 本身采用 Apache-2.0 许可，门户、企业网络能力和商业支持不因 Ocean 开源而变成可自行托管。自托管镜像应固定到经过验证的 Ocean 发布版；当前公开仓库的稳定发布版为 0.45.1，每个集成镜像仍要单独核对兼容标签和变更记录。
第一次连接数据源前还要选定租户区域。EU 租户使用 app.port.io 与 api.port.io，US 租户使用 app.us.port.io 与 api.us.port.io；这是数据与 API 边界，不是前端显示偏好。迁移区域不能靠改一个 Base URL 完成，采购时应取得数据迁移、备份、删除和恢复责任的书面说明。真正先设计的不是首页，而是 Blueprint、Entity、Relation、Ownership 和数据权威。
先把服务从网址变成有身份的实体
Blueprint 是类型定义，Entity 是符合该类型的实例。可以把 Blueprint 理解为带关系的 JSON Schema：它定义属性名称、类型、必填项和与其他 Blueprint 的关系；Entity 则保存稳定标识、显示标题、属性值、关系值和团队归属。service、repository、deployment 不应只是三个页面，它们是三类生命周期不同的对象。字段和映射变化前可对照 Port 数据模型文档 检查当前支持的类型。
一个服务的稳定身份应与显示名分离。identifier 用于 API、关系和自动化，改名后也应尽量保持不变；title 面向人，可以随品牌或业务语言变化。把仓库 URL 当唯一身份很方便，但仓库迁移、拆分或归档会让所有关系一起断裂。更稳妥的做法是给服务分配组织级不可复用标识，例如 payment-api，仓库只是服务的一个关系或属性。
下面是可用于 Builder、API 或 IaC 评审的最小服务 Blueprint。required 决定新实体能否缺少字段；属性类型一旦承载数据，再从 number 改成 string 之类的变更通常需要新字段、数据迁移和旧字段删除，不能把模式编辑当无损操作。
{
"identifier": "service",
"title": "Service",
"ownership": { "type": "Direct" },
"schema": {
"properties": {
"lifecycle": {
"type": "string",
"enum": ["experimental", "production", "deprecated"]
},
"tier": { "type": "string", "enum": ["tier-1", "tier-2", "tier-3"] },
"runbook": { "type": "string", "format": "url" },
"last_verified_at": { "type": "string", "format": "date-time" }
},
"required": ["lifecycle", "tier"]
},
"relations": {
"repository": {
"title": "Repository",
"target": "repository",
"required": false,
"many": false
},
"depends_on": {
"title": "Depends on",
"target": "service",
"required": false,
"many": true
}
}
}配置影响要在建模时说透。many: false 表示单值关系，适合“当前主仓库”；many: true 适合依赖列表。Port 的关系不能同时设置 many: true 与 required: true，因此“至少一个依赖”不能靠该组合表达，需要在导入校验或 Scorecard 中检查。直接 Ownership 把团队写在实体上；继承 Ownership 沿指定关系路径取得上游团队，适合 deployment 从 service 继承 Owner。继承减少重复，却会让一次关系断裂同时丢失归属，必须对空 Owner 建告警。
启用租户并完成第一个闭环
启用需要组织管理员账号、待接入系统的管理员或安装权限，以及一个明确的数据试点。先选十几个有真实 Owner 的服务，不要一开始导入全部仓库。组织管理员在 Port 创建组织后进入 Builder，确认默认的 User、Team 和 Service 模型，再连接一个 Git 提供方。官方 Git 集成通常会为仓库创建实体；默认模型可以改，但模型变化后映射也必须同步调整。
最小闭环按下面顺序执行：
在 Builder 创建或确认 service Blueprint，固定 identifier、lifecycle 和 ownership 语义。安装 Git 集成，只授权试点组织或仓库集合，禁止使用个人全组织 PAT。触发 resync，在 Catalog 搜索一个试点 Entity。
检查 Entity 的 $identifier、$team、仓库链接、生命周期和来源字段。在源仓库修改一项受映射字段，再次同步，确认同一 Entity 被更新而不是新建副本。删除测试映射前先关闭删除传播，导出试点实体快照，再卸载集成。
预期证据不是“目录里出现一行”，而是同一稳定标识经历更新后实体总数不增加，Owner 与 Team 标识一致，集成运行日志显示成功，关系目标可解析。若重新同步后出现 payment-api 与 payment_api 两条记录，说明标识规范或映射转换不一致；继续扩大导入只会扩大重复资产。
托管门户仍有本地工具链。团队可以把 Blueprint、Scorecard、集成映射和权限定义放入 Terraform，使用 terraform plan 审查变化；也可以通过 API 做只读验收。CLI 或 IaC 的版本应在锁文件中固定，升级前查询 Port Provider Registry 和官方文档，而不是在文章或脚本里永久写死版本。
用关系表达运行事实而不是复制字段
关系把实体图连接起来：repository 构建 service，deployment 部署 service，service 依赖 service，service 属于 system，incident 影响 service。关系目标必须先存在；如果同步顺序相反，源实体可能先到而目标未到，关系为空或映射失败。应通过重同步、创建缺失目标实体或调整发现顺序修复，不能把目标名称复制成普通字符串后假装关系成立。
Mirror Property 会沿关系读取目标实体的属性。例如 deployment 可以镜像 service 的 tier，页面和 Scorecard 因而能在部署上下文使用服务等级。它是查询投影，不是第二份权威数据：服务 tier 改变后，镜像值随关系重新计算。若把 tier 同时写入 service 和 deployment 两边，就必须回答哪个覆盖哪个、延迟多久算过期，否则会出现两个都“正确”的冲突值。
做一次正反实验能暴露模型缺陷。正向实验先创建 Team、Repository、Service，再让 Service 关联 Repository 并归属 Team；查询时应看到关系可点击、Owner 非空。反向实验故意提交一个不存在的 repository 标识，或把源系统名称直接当标识。判据是导入日志出现映射或关系解析问题，Entity 的关系为空，Scorecard 把它标为未知或失败；不应自动把普通文本当成一个可信 Repository。
# port.yml：仓库内声明的示意，真实字段需与租户映射一致
identifier: payment-api
title: Payment API
blueprint: service
properties:
lifecycle: production
tier: tier-1
runbook: https://example.com/runbooks/payment-api
relations:
repository: payment-api-repo
team:
- payments仓库内的 port.yml 用于声明由 GitOps 管理的实体；集成自身的 port-app-config.yml 则定义从外部数据到 Port 的映射，两者不是同一个文件。前者回答“这个仓库声明什么实体”，后者回答“集成怎样采集和转换资源”。混淆后常见现象是文件已合并但目录不更新，或集成配置变化却被误以为是业务实体变更。
Ocean 和集成决定数据怎样跨越边界
Ocean 是 Port 的集成框架。托管集成由 Port 运行，启用快、基础设施负担小，但第三方 API 返回的数据和凭证会进入托管执行边界；自托管集成运行在自己的容器、ECS、虚机或 Kubernetes 中，可以访问内网 API，也把网络、升级、日志、伸缩和凭证轮换责任留给团队。自托管并不等于数据不出网：映射后的 Entity 和可选原始样本仍会发往所选区域的 Port API。托管 Custom Integration 从官方公布的区域静态地址访问源 API；自托管实例则需要出站访问对应区域的 api/ingest 地址。严格网络环境可评估 Enterprise 的 AWS PrivateLink 与 IP restriction，但这些是商业能力，不能从免费租户行为推断。选择依据是数据边界与连接方向，而不是哪种按钮更少。自定义接口的安装层和资源映射字段以 Ocean Custom Integration 配置 为准。
自托管 Ocean Custom Integration 的最小配置分两层：安装层提供 Port Client ID/Secret、第三方 API 地址和认证；resource mapping 决定 endpoint、JQ 选择和 Entity 映射。官方当前默认会把 initializePortResources 和 sendRawDataExamples 设为 true：前者可能创建默认 Blueprint 和映射，后者会向 Port 发送第三方原始样本。已有目录或敏感数据环境必须显式关闭，再经过差异审查和脱敏批准后按需开启。OCEAN__SCHEDULED_RESYNC_INTERVAL 的单位是分钟；过短会触发第三方限流和 Port 写入压力，过长会扩大目录陈旧窗口。
# 只展示启动结构；凭证必须来自进程级 Secret 注入
docker run --rm --name port-ocean-custom `
-e OCEAN__PORT__CLIENT_ID=$env:PORT_CLIENT_ID `
-e OCEAN__PORT__CLIENT_SECRET=$env:PORT_CLIENT_SECRET `
-e OCEAN__PORT__BASE_URL=$env:PORT_BASE_URL `
-e OCEAN__INITIALIZE_PORT_RESOURCES=false `
-e OCEAN__SEND_RAW_DATA_EXAMPLES=false `
-e OCEAN__SCHEDULED_RESYNC_INTERVAL=60 `
-e OCEAN__INTEGRATION__IDENTIFIER=internal-service-catalog `
-e OCEAN__INTEGRATION__TYPE=custom `
-e 'OCEAN__EVENT_LISTENER={"type":"POLLING"}' `
-e OCEAN__INTEGRATION__CONFIG__BASE_URL=$env:SOURCE_API_BASE_URL `
-e OCEAN__INTEGRATION__CONFIG__AUTH_TYPE=bearer_token `
-e OCEAN__INTEGRATION__CONFIG__API_TOKEN=$env:SOURCE_API_TOKEN `
-v "${PWD}/port-app-config.yml:/app/port-app-config.yml:ro" `
ghcr.io/port-labs/port-ocean-custom:<pinned-version>启动后先看容器日志是否完成认证和首次 resync，再在 Catalog 比较源对象数、成功实体数、过滤数和失败数。固定镜像摘要或明确版本，不使用长期漂移的 latest。健康探针只能证明进程可访问，首次全量同步完成、失败数归零和源/目标计数对账才证明链路成立。清理时先停止调度、导出测试 Entity、关闭删除传播并确认没有仍在运行的 resync，再删除测试 Entity、映射和集成；直接删容器只会停止同步，不会自动清除 Port 中已摄取的数据。
同步的底层模型是“外部资源快照或事件 -> 映射 -> upsert Entity -> 处理关系与删除”。相同 Blueprint 与 identifier 会更新实体；identifier 变化会制造新实体。删除传播尤其危险：源系统临时不可见、权限收窄或 API 分页失败，都可能被错误解释为资源已删除。对关键目录先设置删除阈值或保护策略，观察完整 resync 的差异，再允许清理。多个 exporter 实例、重同步中断和持续触发新 resync 还会导致全量同步永远不能完成，表现为目录某些分区长期陈旧。
在 Action 与 Workflow 之间建立可观察执行
Port 的 Actions/Automations 仍能触发 GitHub Actions、Jenkins、Webhook 等后端，并生成 Action Run；Actions 与 Automations 概览 把它们归为 legacy，但同时说明仍受完整支持。Workflows 提供图式多步骤编排、条件分支和统一工具入口，却仍处于 Open Beta，没有 SLA 或保证的问题解决时限。生产设计不能因为“推荐新建使用”就把 Beta 当稳定替代：先在无副作用流程验证节点语义、并发编辑冲突、审批、失败终态和回滚，再决定新流程采用 Workflow，还是继续使用已受支持的 Action。存量迁移要盘点调用方、权限、后端类型和回调协议，不能只在 UI 中重建按钮；旧 GitHub App 后端处于 sunset 时，应迁到 GitHub Ocean 或其他受支持后端，而不是顺带改写全部业务逻辑。
一个可靠工作流至少包含输入模式、实体上下文、权限、幂等键、审批、执行后端、超时、状态回写和补偿。以“创建临时数据库”为例，输入包含服务、环境、保留时长和容量档位；Workflow 验证服务 Owner，只允许非生产环境，生成 request_id 并调用外部 IaC 流水线。Port 的 Run ID 和用户提供的 request_id 不会天然让下游资源幂等，真正的唯一约束必须落在执行器状态库、IaC workspace 或云资源标签查询上。外部执行器回写运行状态和脱敏日志，失败时按已完成步骤撤销数据库、凭证和目录实体。
正向实验应连续触发两次相同 request_id。预期只有一个数据库资源，第二次返回已有运行或幂等命中，运行记录最终为成功，Entity 关系指向申请服务。反向实验在“资源已创建、目录尚未登记”之间主动让后端失败。预期运行状态为失败，补偿步骤删除资源和 Secret；若补偿也失败，运行必须进入人工处理状态并给出资源标识，而不是显示泛化的红色失败。
{
"request_id": "demo-payment-api-dev-001",
"service": "payment-api",
"environment": "development",
"retention_hours": 8,
"capacity_class": "small"
}输入中的隐藏字段并不等于不会传播。审批通知、Webhook body、Action Run 日志和下游流水线都可能收到完整参数。不要让用户输入云密钥；让执行器根据短期工作负载身份获取权限。Webhook Secret 只用于验证请求来源，不能复用为云管理员凭证。所有回调都要校验运行 ID、签名、时间窗和允许的状态迁移，防止伪造成功或重复回调覆盖终态。
Scorecard 要评估证据而不是字段装饰
Scorecard 绑定 Blueprint，通过 filter 选择 Entity，再按层级和规则计算结果。Scorecard 管理入口 支持 UI、API 与 Terraform，实际字段以目标租户为准。Bronze、Silver、Gold 只有在规则含义递进时才有价值。runbook 非空只能证明存在 URL，不能证明页面可访问、内容属于当前服务或最近验证过。更可靠的标准会组合来源、时间和语义：Owner 存在；生产服务具有 runbook；探测最近成功；证据时间没有超过团队定义的新鲜度窗口。
Port 原生 Scorecard 规则结果围绕 Passed / Not passed 展开，并不会自动产生 unknown、stale、error 三种额外终态。要保留证据故障语义，应先由集成把 evidence_state、evidence_observed_at、collector_error 等字段写入 Entity，再让规则对这些属性做布尔判断，并在页面或聚合视图中展示原始状态。反向实验可以临时撤销只读集成 Token：预期自建证据层把状态写成 error 或让年龄越过 stale 阈值，Port 规则随之 Not passed；若规则仍保持通过且没有时间戳，说明它消费的是陈旧属性。
Scorecard 可通过 UI、API 或 Terraform 管理。删除不可恢复，因此先导出定义并记录适用 Blueprint。规则修改要先在试点过滤器上运行，比较结果分布和未知比例，再扩大范围。把数千实体同时重新评估会消耗集成 API 配额、任务队列和人员注意力；容量预算不只是 Port 请求数，还包括 Git、监控、云 API 的查询量与通知噪声。
权限和 Token 必须在后端形成闭环
Port 中人类用户与 Service Account 都受 RBAC 约束。Admin 能执行组织级管理；Blueprint Moderator 管理特定模型和实体；Member 主要读取并执行获准工作流。SSO 启用后，用户、团队和成员关系来自 IdP，离职与转组应由 IdP 生命周期驱动。直接在 Port 手工修正 SSO 团队成员会产生下次同步覆盖和审计分叉。
目录权限与执行权限是不同的门，而且 legacy Action 与 Open Beta Workflow 的策略语义不能混用。旧 Action 的动态策略在 Blueprint 权限之后求值，只能继续收紧；Workflow 则把 execute permissions 放在 trigger node 中，roles、users、teams 先按 OR 匹配，policy 在静态项未命中时提供另一条判定路径。更危险的是，Workflow 的 machine token 在没有 policy 时会绕过静态检查，因此机器调用必须显式配置 policy 或在下游再次校验资源 Owner、环境和额度。_workflow Blueprint 的读写权限只控制谁能查看或修改定义，不等于谁能触发运行。UI 隐藏工作流不是完整授权，后端触发、审批和回调端点都必须校验；运行可见性也要限制，避免泄漏环境名、资源标识和失败参数。
组织 Client Secret 可通过 Access Token 接口 换取有期限的 Token，不能放在浏览器、仓库或普通日志中。普通 API 自动化优先使用独立 Service Account，授予最小 Blueprint 和动作权限；凭证只在创建响应中出现时立即存入密钥管理系统。但 Ocean 集成目前不支持 Service Account machine token，官方记录的限制涉及 token 校验和审计事件，Ocean 必须按具体集成使用组织级或受支持的源系统凭证，不能照搬普通 API 的 Service Account 方案。GitHub Ocean 的集成动作还明确要求 Port machine token，个人 Token 和 Service Account Token 都不是可互换选项。
轮换流程是签发新凭证、让消费者并行切换、验证新 Token、撤销旧凭证、检查旧 Token 再调用必然失败。只更新 Port Secret 而不重启或刷新 Ocean 进程，会留下“控制台已轮换、运行实例仍持旧值”的半完成状态。SSO 负责登录，SCIM 负责用户生命周期；Port 的 SCIM 需要联系支持启用，当前只处理用户事件而不接受 IdP group push，团队映射仍要单独验证。把“登录成功”当成 Team 与动态权限同步成功，会让离职和转组场景留下越权。
按证据分型排查同步与工作流故障
认证失败通常表现为 Access Token 接口返回 401 或集成启动即退出。先确认 Client ID/Secret 来自正确组织、Secret 没有被换行或模板转义，再用受控环境单独请求 token；不要打印响应中的 Access Token。若 token 成功而实体写入 403，问题已经从认证转为当前机器主体的 Blueprint/RBAC 权限；Ocean 使用组织凭证时不要误按 Service Account 路径排查。
目录为空但集成显示运行时，依次检查源系统授权范围、资源 mapping 的 kind、JQ 过滤、Blueprint identifier 和 resync 日志。实体有了而关系为空，检查目标 Entity 是否先存在、标识大小写和映射后的类型。全量同步反复开始却没有完成，检查同步间隔是否短于一次完整扫描、是否有多个实例消费同一配置，以及第三方 API 限流。
工作流一直处于运行中，先区分后端未收到请求、后端执行未回调、回调被拒绝三类。用运行 ID 串联 Port Run、Webhook 网关和 CI Job；检查回调 Token、签名、状态值和网络出口。修复后不要手工把状态改绿作为验收，要重新执行一个无副作用请求，确认从触发到终态的完整链路。
Scorecard 大面积翻红时先看同一时间是否有集成错误。所有服务一起失败更像证据源或规则变化，少数实体失败才更像服务事实。对规则保留“计算时刻、数据来源、最后成功采集时刻和失败原因”，否则 Owner 只能看到结论，无法修复。
容量、成本和敏感数据会决定架构形态
目录容量由实体数、属性体积、关系边数、更新频率、Scorecard 数量、查询复杂度和工作流运行记录共同决定。一个 Kubernetes 集群可能产生海量短命 Pod；如果每个 Pod 都永久进入门户，目录写入、关系和页面查询会被短生命周期噪声淹没。通常只摄取开发者需要决策的粒度，短命运行对象保留在观测系统，在 Port 中聚合为 deployment 或 workload 证据。
成本评估不能只看席位。公开计价由平台费、席位和套餐容量共同构成，免费入口也有席位、Entity 和自动化运行量限制；PrivateLink、IP restriction、SCIM、SLA、工作区数量和支持响应可能由商业套餐控制。还要计算 Ocean 运行基础设施、第三方 API 配额、跨区数据出口、审计保留、工作流后端、平台团队维护和服务 Owner 更新元数据的时间。Port 的审计页面默认只展示最近一千条，审计事件默认保留九十天、登录访问日志三十天；需要更长证据链时要用 API 持续归档并让合同确认保留责任。采购时应在目标租户逐项验证 SSO、细粒度权限、审计、数据驻留、导出 API、保留和并发限制，不把演示环境行为当合同能力。
服务目录本身是敏感图谱。仓库地址、Owner、依赖、生产等级、漏洞结果、值班链接和云资源标识组合后可以描绘组织攻击面。建立字段分级：普通成员可看服务描述；受限角色可看生产资源和安全结果；凭证永不进入 Entity。原始采集样本、失败 payload、工作流日志和导出文件使用同样的数据等级，并配置保留与删除责任人。
把退出能力作为上线条件
退出前要能分别导出模型、实体、关系、团队映射、Scorecard、Workflow 定义和审计证据。API 导出的 Entity JSON 只是数据快照，不自动包含外部执行器、Secret、SSO 配置和仪表盘语义；Terraform 只能带走由 Terraform 管理的对象。每季度做一次只读导出，并在隔离目录验证数量、稳定标识、关系闭合和敏感字段脱敏。
退出顺序应先冻结模型和工作流变更，停止新写入，再做最终同步与导出；随后把消费者切到新目录，禁用会产生外部副作用的 Workflow，撤销 Port 和第三方集成 Token，停止 Ocean，最后按保留政策删除租户数据。先卸载集成再导出会丢失最新来源信息；先删除实体可能触发自动化或让关系快照不完整。
长期治理需要三类 Owner：平台 Owner 维护租户、集成和权限；模型 Owner 审批 Blueprint 与字段权威；服务 Owner 维护实体事实和整改 Scorecard。每次模式变更都经过试点、差异预览、回滚字段和迁移完成率检查。每次集成升级都验证实体数量不突变、重复率不增长、关系缺失率不恶化、同步时长不持续超过调度间隔。做到这些，Port 才是一套可验证的工程控制面，而不是一张越来越漂亮、越来越不可信的链接页。