Link Visibility Notes：公开链接与私有边界

Method Note · published · 2026-06-08

记录我如何在公开作品集中区分 public、private、internal、pending 和 unavailable 链接。

Cover

Link Visibility Notes：公开链接与私有边界 writing cover.

Why this matters

公开站点最容易出问题的地方不是设计或内容，而是"链接边界"。一个看似无害的链接可能暴露私有仓库、内部工作流、后台地址或敏感入口。

我在整理 conanxin-homepage 项目档案时发现了这个问题：很多项目有 GitHub 仓库链接，但这些仓库大多是私有的。如果直接显示私有仓库的 URL，虽然仓库本身受密码保护，但 URL 的暴露仍然是一种信息泄露——它告诉访问者"这个仓库存在"，可能暴露项目结构、技术栈或合作者信息。

更隐蔽的问题是内部链接。比如 Cloudflare Dashboard 地址、GitHub Actions 配置页面、邮件后台——这些链接对站点的作者来说"显而易见"，但对访问者来说不应该可见。

Core idea

链接可见性的核心原则是：公开站点只展示公开内容，私有内容即使"链接本身无法访问"，也不应该显示 URL。

这个原则的依据：

• 信息最小化：访问者只需要知道"有什么"，不需要知道"在哪里"
• 防御深度：即使仓库密码很强，不暴露 URL 也是额外的安全层
• 可信度：一个标记为 "Private repository" 的项目比一个显示 404 的链接更可信
• 维护性：如果仓库从 private 变为 public，只需要改一个配置，不需要改页面内容

Notes

链接是作品集的边界

个人作品集是一个"公开档案"，但它有明确的边界。不是所有东西都应该公开：

• 公开：项目主页、公开仓库、公开文档、公开演示
• 私有：私有仓库、未发布代码、内部测试环境
• 内部：后台管理、配置页面、监控面板
• 待补充：计划公开但尚未准备好的内容
• 不可用：暂时无法访问的内容

这个边界不是技术限制，而是设计决策。它定义了"我的公开身份"和"我的私人工作"之间的分界线。

五级可见性如何工作

HP-13 建立的五级可见性系统：

| 级别 | 页面显示 | URL 处理 | 示例 | |------|----------|----------|------| | public | 真实 URL 链接 | 显示完整 URL | /search/ /tags/ /map/ | | private | "Private repository" | safeUrl 为空 | GitHub 私有仓库 | | internal | "Internal workflow" | safeUrl 为空 | Cloudflare Dashboard | | pending | "Demo not public yet" | safeUrl 为空 | 计划中的演示 | | unavailable | "Not available" | safeUrl 为空 | 已下线的服务 |

这个系统的关键机制是 safeUrl：只有 public + publishUrl=true 时，safeUrl 才有值；其他情况 safeUrl 为空字符串，页面渲染时不生成 href。

safeUrl 为什么重要

safeUrl 是链接安全的技术保障。它的规则：

• public + publishUrl=true → safeUrl = 真实 URL
• 其他所有情况 → safeUrl = ""

这个规则在 build-links.mjs 中强制执行，不依赖人工检查。它的好处：

• 自动化：不需要每次添加链接时手动判断
• 一致性：所有链接遵循相同的规则
• 可验证：可以通过脚本检查是否有违规链接
• 可回滚：如果误标记了 visibility，改配置即可，不需要改页面

Pending 比虚构更可信

一个常见的 temptation 是：为 pending 的内容虚构一个链接，让页面看起来更"完整"。但虚构链接的问题：

• 不可验证：访问者点击后发现不存在，降低可信度
• 维护负担：需要记住哪些链接是虚构的，未来补链接时容易遗漏
• 误导性：给访问者错误的期望

标记为 "Demo not public yet" 比虚构链接更诚实。它告诉访问者"这个内容存在，但还没准备好公开"，这是一种可验证的状态声明。

如何逐步补公开 Demo

链接可见性系统的另一个作用是支持"渐进公开"。一个项目可以：

1. 初始状态：所有链接标记为 private 或 pending 2. 准备公开：把 homepage 链接改为 public 3. 补充 Demo：把 demo 链接改为 public 4. 开放仓库：如果仓库变为 public，把 repository 链接改为 public

这个渐进过程不需要重构页面，只需要改 data/links.json 中的 visibility 和 publishUrl。

conanxin-homepage 的链接状态变化：

• HP-13 初始：17 public，7 private，1 internal，4 pending
• HP-15 补充：Demo Gallery 增加了 5 个 public 的 demo 链接
• 未来：随着更多项目公开，private/pending 会逐渐减少

How I use it

链接可见性系统直接影响了 conanxin.com 的维护方式：

• 集中管理：所有链接在 data/links.json 中统一管理，不散落在 HTML 中
• 自动验证：build-links.mjs 自动检查链接安全，禁止 dashboard URL 和 IP 地址
• 渐进公开：项目从 private 到 public 的过程是配置变更，不是页面重构
• 可信展示：访问者看到 "Private repository" 比看到 404 更信任站点

Related

Next

• 定期审计链接状态
• 为更多项目补充公开 Demo
• 设计链接可见性的自动化监控