Ivan's Blog
主题

Service ports

Service ports 表示端口号、bind 地址、dev/prod 暴露方式和多组件端口分工本身就是仓库的稳定 contract。它不是“服务都会有端口”这种空泛事实，而是说端口设计会直接影响本地预览、反向代理、权限边界、自动化脚本和故障排查。 这个 Topic 关注的是端口作为系统边界的那一面。

  • 服务
  • 运维

目录

Definition

Service ports 表示端口号、bind 地址、dev/prod 暴露方式和多组件端口分工本身就是仓库的稳定 contract。它不是“服务都会有端口”这种空泛事实，而是说端口设计会直接影响本地预览、反向代理、权限边界、自动化脚本和故障排查。

这个 Topic 关注的是端口作为系统边界的那一面。它通常会和 Rust web service、Dockerized dev、React app 一起出现，但不替代这些 Topic：相邻 Topic 解释服务或 UI 是什么，Service ports 解释它们怎样在本地、容器和反向代理环境中被暴露出来（projects/proxy-broker.md、projects/xp.md）。

When to use

当 README、project snapshot、env 文档、CLI flags、compose 配置或本地脚本明确写出默认端口、可覆盖端口、loopback/public bind、端口组分工或反向代理前提时使用。命中条件不是“监听了网络”，而是端口本身已成为维护者必须记住和审查的事实。

如果一个改动会改变默认端口、bind 地址、base path、反向代理暴露方式、dev/prod 端口分离、多组件端口矩阵或本地预览租约策略，就应该命中 Service ports。若仓库只有一个未文档化的临时监听端口、且不影响交付和运维约定，则不必提升为 Topic。

Habits / defaults

  • 默认端口应显式且稳定，特别是多组件系统。高位固定端口 + 文档化覆盖入口，比“随机找空闲端口”更适合长期维护和脚本化验证（projects/xp.md、projects/blog-26.md）。
  • 端口和 bind 必须有单一 override surface，例如 env 或 CLI flags，避免 magic number 分散在前端脚本、后端代码和 compose 文件里（projects/proxy-broker.md、projects/tavily-hikari.md）。
  • 多组件系统要把 API、UI、docs、gateway、supervisor/dev tooling 拆开表达。像 projects/blog-26.md、projects/proxy-broker.md 这种端口矩阵，本质上是在表达系统边界，而不是单纯开发便利。
  • 默认暴露通常应偏向 internal/loopback，公开访问交给反向代理、Forward Auth 或显式 base path；端口设计本身就是安全边界，不是最后再补的部署细节（projects/proxy-broker.md）。
  • owner-facing localhost handoff 不是“把默认端口告诉别人”这么简单；Topic 回答里应默认考虑端口租约、后台会话持有和与现有本机服务冲突的处理方式。
  • 端口一旦被写进 docs、scripts 或 release artifact，就要把它当 contract 管，而不是认为“以后随便改一改再说”。

Reference implementations

  • projects/proxy-broker.md：适合说明 loopback 默认值、多个严格本地端口和反向代理/Forward Auth 怎样共同形成安全边界。
  • projects/xp.md：适合说明 Web、Storybook 和服务端口如何成组出现，并被文档和脚本共同依赖。
  • projects/tavily-hikari.md：适合说明容器部署里 PROXY_PORT、PROXY_BIND 和 volume/data path 怎样一起构成运行 contract。
  • projects/blog-26.md：适合说明多 runtime/gateway 项目里的端口矩阵不是附带信息，而是系统地图的一部分。

Failure modes

  • 只记录端口号、不记录 bind/base path/override 入口，会让文档表面正确但运行仍然不可复现。
  • 把 Service ports 当成整个仓库的总括标签，忽略 Rust web service、Dockerized dev、React app 等相邻 Topic，会让后续 Agent 无法判断真正应该验证的是 runtime、协议、UI 还是交付链路。
  • 直接把默认端口 handoff 给 owner，却不处理本机冲突、后台持有和租约，会让“能打开”变成一次性巧合，而不是稳定预览路径。
  • 把 loopback 改成 public 或把多个端口偷偷并到一个入口，若不回写 Topic，通常会制造安全和运维语义漂移。

Evidence index

  • projects/dockrev.md
  • projects/mineru-remote-mcp.md
  • projects/tavily-hikari.md
  • projects/xp.md
  • projects/octo-rill.md
  • projects/proxy-broker.md
  • skills/style-playbook/references/data/topics/service-ports.json

相关内容