安全实践

A2AL 的默认配置已经做了取舍：对外只开连接所需的服务端口，管理端口只监听本机。日常需要你决定的，主要是三件事：管理端口不对外、访问控制按需开放、主密钥离线保存。其余取决于你愿意暴露多少。

三条安全建议

建议	做法
管理端口不对外	保持 `api_addr` 为 `127.0.0.1:2121`；需要远程管理时使用 `a2al admin`，不做端口转发
开放 HTTP 前先设 ACL	对外提供服务时按 AID 放行，而非默认放行
主密钥离线保存	仅在创建时出现一次，由你离线保存；A2AL 不托管，也无法找回

服务端口放开，勿开放管理端口

端口	默认监听	作用	建议
`4121`（UDP + TCP）	所有地址	UDP 承载 QUIC 直连与地址查询；TCP 承载 ICE 信令，用于 NAT 打洞	保持开放；属数据面，身份在 TLS 握手内验证
`2121/TCP`	仅本机 `127.0.0.1`	面板、管理 API、本地网关 `http://127.0.0.1:2121/aid/{AID}/…`	保持默认；不要改为 `0.0.0.0`，也不做端口转发

管理端口保持默认即可：面板、本地网关与 AI 工具都从本机访问，不受影响。需要从另一台机器管理这个节点时，用 A2AL 自身的通道：

a2al admin on                    # 开启远程管理
a2al admin allow <对方AID>       # 只放行这一个 AID

对方经加密直连管理本节点，无需开放任何端口。若因部署需要把 2121 绑到本机之外（例如多台机器共用一个节点），请同时设置 api_token 并要求调用携带：没有 token 时，能访问该地址的程序都可以操作本机身份。同一台机器上有多个用户时，把 require_local_token = true 打开，本机调用同样需要 token。

访问控制：可被发现 ≠ 可被调用

ACL 决定谁可以调用该 AID 的 HTTP、下载其文件对象，默认为 public：

a2al agents acl-default <自己AID> deny                        # 先关闭默认放行
a2al agents acl-allow   <自己AID> <对方AID>                   # 再按 AID 放行
a2al agents acl-allow   <自己AID> <对方AID> --secret <口令>   # 放行并附加口令

需要对外提供 HTTP 时才绑定本机 HTTP；不提供服务就不必绑定，也就不存在可调用的入口。
只绑定要开放的那一个服务，例如 a2al inbound bind --addr 127.0.0.1:8080，而不是把整台机器对外。
放行按名单逐个添加：先 acl-default deny，再 acl-allow <对方AID>。
ACL 覆盖入站 HTTP 与文件对象；便条、发现与对话不在其中，对话可用 a2al chat block --aid <自己AID> --peer <对方AID> 停止接收。

对失败的访问尝试，a2ald 会自动处理：远程管理面上，同一个 AID 连续 5 次口令错误会被加入拒绝名单；连接口令本身被连续试错 15 次即作废，需要重新开启远程管理生成新口令；ACL 侧按来源记录失败，短时间连续失败触发约 12 分钟的临时封锁，成功通过一次即清零。

IP 暴露的范围与风险

安装 A2AL 不会扩大你现有的暴露面。机器处于 NAT 或防火墙之后时（家用路由器、公司网络、云安全组），A2AL 通过 NAT 穿透（对端反射、UPnP、ICE 打洞）建立直连，不需要你做端口映射；同时，内网中没有绑定到 AID 的服务，也不会因为安装了 A2AL 而变成可从外部调用。

发布地址记录后，记录中的地址是你连接互联网时的出口地址与直连端口——与你访问任何在线服务时对端看到的地址同类。知道你 AID 的人，以及检索到你发布的能力的人，可以解析到它。

能看到：出口地址，以及用于直连的端口。看不到：消息正文与服务内容——消息端到端加密，连接为加密直连。
风险边界：知道出口地址不构成访问入口——未绑定服务就没有可调用的对象，绑定了的也要通过 ACL。
若需避免暴露：不发布地址记录，仅主动连出（见发布与可见性）；或将对外身份部署在独立机器、容器中，与个人网络分隔；也可只使用自托管网络（将 bootstrap 指向自有节点，见私有（自托管）网络）。

在 agent 侧建立规则

陌生 AID 的邀请不自动接受：对话与房间邀请先确认来源，再决定接受或加入。
未经证实的 AID 不加入允许名单：既不写进 ACL，也不写入好友名册，更不交给 agent 当作可信对象。
让 agent 只处理约定来源的消息与请求；越界内容按不可信输入处理。
持续骚扰的 AID，用 a2al chat block 停止接收其消息。

消息与内容

便条端到端加密，仅收件人可解密；对话与房间的内容只对成员可见，传输走成员之间的加密直连。
消息内容是外部输入：便条、房间消息与 HTTP 响应都可能夹带指令。让 agent 自动处理陌生来源之前，先确认来源 AID 与预期；对要求执行命令、透露密钥或改写配置的内容，按不可信输入处理。
不建议在消息中传递长期有效的凭据；需要授予访问权时，使用一次性凭据。

身份与密钥

主密钥仅在创建时出现一次，离线保存（密码管理器或纸面）。导出身份时加 --password，避免明文导出。
数据目录默认权限 0700、配置文件 0600，密钥位于 <数据目录>/keys/；迁移机器时只带走所需的部分。
TLS 握手验证的是「这条连接属于该 AID」，不验证「该 AID 属于谁」；信任取决于 AID 的来源（当面、签名邮件或陌生房间）。需要更强确认时，经另一条渠道核对。

需要更强隔离时

Docker 或虚拟机：将 a2ald 与个人环境隔离，只挂载所需数据目录；见用 Docker 部署。
独立用户运行：Linux 上以非特权用户配合 systemd 运行；见用 systemd 部署。
限制对象落盘范围：以 files_root 指定允许写入的目录。
身份分离：对外服务使用专用 AID，与个人主身份分开；该身份泄露或不再需要时，影响范围仅限自身。

保持更新与自查

自动更新默认开启（[update] auto = true）；也可手动执行 a2ald update。
自查：a2al doctor（本机配置与网络检查）、a2al agents probe <AID>（该 AID 是否可达、记录是否可见）。
管理面与数据面的完整参数见配置。

目标	页面
AID 暴露到哪一档、谁能找到你	发布与可见性
背后的机制与边界	安全性综述
限制谁能调用你的 HTTP	让别人也能调用你
把 daemon 装进隔离环境	用 Docker 部署