02/Documentation
安全性，运行前必读
Collie 暴露的内容、防御机制以及将设备配对为写入凭据
Collie 在设计上即提供对您机器的远程 shell 访问权限。 单次 Collie API 调用即可将任意按键直接发送至活动的终端窗格。任何对该 URL 具有网络访问权限的人都可以读取所有窗格（源码、密钥、环境变量、agent 输出）并以你的用户身份执行命令。
没有沙箱，也没有命令白名单，因为过滤命令会违背该工具的初衷。请将该 URL 视为 root 登录对待。
风险模型
关键安全边界与风险：
- 它以您的用户权限运行。 Collie 继承您的全部访问权限，包括
~/.ssh、git push --force、rm -rf和sudo。 - 所有本地系统用户均可访问该端口。 标准终端多路复用器套接字（
tmux、zellij、herdr）使用文件系统权限来限制其他本地用户的访问。Collie 监听本地 TCP 端口，这会将其暴露给所有本地 UID。配对或单设备网关可以限制写入权限，但所有本地用户仍可执行读取操作。这能降低执行风险，但无法防止数据泄露（ARCHITECTURE.md §6）。 - 写入操作会记录到
<state-dir>/audit.log，即~/.local/state/collie/audit.log，除非COLLIE_STATE_DIR移动了它。服务器会记录所有传入的按键、回复、文件上传以及面板/标签页生命周期事件。请注意，审计日志提供的是事后可见性，而非访问控制（ARCHITECTURE.md §6）。 - 默认防御控制。 Collie 仅严格绑定到环回接口，仅通过
tailscale serve或等效的反向代理路由流量，并应用严格的 CSP 规则、同源检查和 host 标头验证。窗格输出渲染为 React 文本节点，而非innerHTML。切勿使用tailscale funnel或暴露原始端口。若要授权特定硬件，请直接使用 配对；或者，如果你的代理注入了设备 ID，请使用下方的两个COLLIE_DEVICE_*变量。
| 变量 | 作用 |
|---|---|
COLLIE_ALLOW_NON_LOOPBACK_BIND=1 | 选择退出仅限环回的绑定；未设置时，bridge 会拒绝绑定到 0.0.0.0。 |
COLLIE_ALLOW_ANY_HOST=1 | 禁用 host 标头验证（默认开启且失败时拒绝访问）。 |
COLLIE_TRUSTED_USER | 拒绝缺少或不匹配 Tailscale-User-Login 标头的请求。 |
COLLIE_TRUSTED_USER_OPTIONAL=1 | 允许缺少 Tailscale-User-Login 标头（标记的节点绝不会发送该标头）。 |
COLLIE_DEVICE_HEADER | 代理注入包含设备 ID 的标头名称。 |
COLLIE_DEVICE_ALLOWLIST | 允许写入的以逗号分隔的设备 ID 列表；所有其他设备保持只读（docs/deployment.md）。 |
🚫 切勿将tailscale funnel与 Collie 配合使用。 Funnel 会将流量路由到公网，而tailscale serve则将访问限制在你的私有 tailnet 内。Collie 不支持在 Funnel 上运行。
使用 Tailscale ACL 和 COLLIE_TRUSTED_USER 进一步限制访问。按原样提供，不提供任何保证。
哪些数据会离开你的机器
默认情况下以及依策略而言：没有任何数据。Collie 不发送安装事件、使用统计、崩溃报告或分析数据。没有任何 flag 可以启用它们。
唯一未经提示的主动出站请求是更新检查：向 GitHub 公开 tags API（bridge/update.ts）发送一个匿名的 HTTPS GET 请求，用于将你的版本与最新标签进行比对。该请求不携带关于你或你机器的任何数据，仅包含静态 User-Agent collie-update-check。
如果将来加入数据收集，明确的 opt-in 是最高限度：默认关闭，以显式问题询问，绝不通过 flag 携带或默认开启。移除此承诺属于破坏性变更（ADR 0034）。
配对设备：写入凭证
bin/collie pair # on the host — prints an 8-character code and a QR code, good for 10 minutes在手机上打开 Collie，进入 设置 → 已配对的设备，输入配对码并为设备添加标签；也可以扫描命令输出的二维码，直接打开该界面并自动填入配对码。手机会保存返回的 token。Collie 仅保留其哈希值，且该 token 仅显示一次。无需重启进程；运行中的守护进程会在下一次请求时应用配对与撤销操作。
这两个设备关卡解决不同的问题，你可以运行其中一个、两个都运行，或者都不运行：
| 询问 | 信任 | 吊销方式 | |
|---|---|---|---|
COLLIE_DEVICE_HEADER | 此设备是否在操作员的列表中？ | 你的代理，用于注入其已净化的名称 | 编辑 COLLIE_DEVICE_ALLOWLIST，然后重启 |
| 配对 | 此设备是否持有我签发的凭证？ | 网络上的任何内容都不信任 | collie devices revoke <label>：实时生效 |
配对无需额外的基础设施。适用于不存在注入标头的代理的直接 tailscale serve 配置。
这两个选项都仅限制写入权限。只要通过同源检查，读取请求对任何来源保持开放。
bin/collie devices list # what holds a credential, and when each was last seen
bin/collie devices revoke old-phone # effective immediately, no restart仅当至少配对了一台设备时，写入门控才会生效。在运行 collie pair 之前不会配对任何设备，因此在此之前读写操作照常运行。请先配对你当前的手机。撤销最后一台设备会再次禁用门控，以防止被锁在门外。
验证码尝试失败五次后将失效，需要再次运行 collie pair。
在运行多个实例的主机上，在命令前加上 COLLIE_INSTANCE=<name>，并在手机上打开该特定实例的 URL（单台主机上运行多个 Collie 实例）。