anoni-net
diff --git a/‎docs/en/community/pin-ipfs-mirror.md‎
Lines changed: 49 additions & 4 deletions b/‎docs/en/community/pin-ipfs-mirror.md‎
Lines changed: 49 additions & 4 deletions
diff --git a/‎docs/zh-CN/community/pin-ipfs-mirror.md‎
Lines changed: 50 additions & 5 deletions b/‎docs/zh-CN/community/pin-ipfs-mirror.md‎
Lines changed: 50 additions & 5 deletions
@@ -6,7 +6,7 @@ icon: simple/ipfs
 
 # :simple-ipfs: Help pin the site's IPFS mirror
 
-Alongside the main site, the anoni.net docs are also published as an IPFS mirror, so the content stays readable when the main site is blocked or taken down. Content on IPFS only survives while some node pins it, and right now only the community's own node does. Every extra node that helps pin is one more complete copy on the network, and more resistance to takedown.
+Alongside the main site, the anoni.net docs are also published as an IPFS mirror, so the content stays readable when the main site is blocked or taken down. Content on IPFS only survives while some node pins it, and only a handful of nodes currently serve this mirror, with the community's own node carrying most of it. Every extra node that helps pin is one more complete copy on the network, and more resistance to takedown.
 
 This page walks you through running one always-on IPFS node plus a small scheduled script that keeps up with the latest version automatically. It works the same on Windows, Linux, and macOS, with or without Docker.
 
@@ -29,6 +29,18 @@ If IPFS is new to you, one idea makes the rest of this page make sense. For the
 
 That is exactly what the script does: resolve IPNS to the current CID, pin that new CID, then drop the old one. Because the CID changes, this has to run periodically, which is why it's scheduled.
 
+### Three lookalike identifiers
+
+IPFS has three identifiers that look alike and do different jobs. Paste one into the wrong field and the tool rejects it outright.
+
+| Identifier | Starts with | Changes? | What it's for |
+|---|---|---|---|
+| CID | `bafybei…` | New one every publish | Pointing at one specific version |
+| IPNS name | `k51qzi…` | Fixed | Getting the latest version, which is what pinning uses |
+| Peer ID | `12D3KooW…` | Fixed | Pointing at one specific node |
+
+Pinning the docs site only needs the IPNS name. The Peer ID comes up when you want your own node to hold a steady connection to the community node, covered under "Advanced: keep a steady connection to the community node" below.
+
 ## How it works (why a schedule is enough, no notification needed)
 
 Nobody has to tell you "a new version is out." IPNS is the shared sync point, and your script resolves it to get the latest CID by itself. When the site publishes, it just updates IPNS as usual; your side resolves every few hours, notices the change, and pins the new version. No manual coordination anywhere.
@@ -38,6 +50,7 @@ Nobody has to tell you "a new version is out." IPNS is the shared sync point, an
     The site's IPFS coordinates (public values, use them directly):
 
     - IPNS name: `k51qzi5uqu5dlfm2jj0f70ex3r3babmwy8qh071inwknttr7wqa3uhdwvlmrmw`
+    - Node Peer ID: `12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9` (only needed if you set up peering)
     - Open in a browser: [https://anoni-net.ipns.dweb.link/](https://anoni-net.ipns.dweb.link/){target="_blank"}
 
 Each run does this: resolve IPNS to the current CID, pin the new CID, unpin the previous one, reclaim space. The script confirms the new version pinned successfully *before* dropping the old one. If resolving or fetching fails, it keeps the copy you already have and never empties your node.
@@ -51,17 +64,25 @@ For pinning to fetch the content, your machine needs a continuously running IPFS
     Install [kubo](https://docs.ipfs.tech/install/command-line/){target="_blank"}, IPFS's official command-line implementation. On macOS you can use Homebrew:
 
     ```bash
-    brew install ipfs
+    brew install kubo
     ```
 
+    The Homebrew formula was renamed from `ipfs` to `kubo`. The old name still installs it, but the service commands below need the `kubo` name. Both Intel and Apple Silicon are supported.
+
     On Linux, download the kubo build for your architecture from the [official guide](https://docs.ipfs.tech/install/command-line/){target="_blank"}. Then initialize and start the daemon:
 
     ```bash
     ipfs init          # first time only
     ipfs daemon
     ```
 
-    To keep the daemon running long-term, use a systemd user service on Linux, or `brew services` / launchd on macOS. For a quick test, running `ipfs daemon` in the background is fine.
+    To keep the daemon running long-term, use a systemd user service on Linux. On macOS the Homebrew formula ships a service definition, so a single command keeps it resident and starts it at login:
+
+    ```bash
+    brew services start kubo
+    ```
+
+    For a quick test, running `ipfs daemon` in the background is fine.
 
 === "Windows"
 
@@ -184,10 +205,34 @@ ipfs pin ls --type=recursive | grep "${CID#/ipfs/}"
 
 You can also open it on your local gateway and check it renders: `http://127.0.0.1:8080${CID}/`. Docker users: replace `ipfs` above with `docker exec ipfs_host ipfs`.
 
+## Advanced: keep a steady connection to the community node (optional)
+
+Pinning works off the IPNS name alone, and the DHT takes care of finding the content. Fetching a full mirror for the first time can drag on when DHT lookups are slow or come back empty. To hold a fixed connection between your node and the source node, configure kubo's peering.
+
+Edit `~/.ipfs/config` and add a `Peering` block at the top level:
+
+```json
+"Peering": {
+  "Peers": [
+    { "ID": "12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9" }
+  ]
+}
+```
+
+`Addrs` can be omitted, and kubo will look the addresses up in the DHT. Restart the daemon to apply. Docker users edit `./ipfs-data/config` instead, then run `docker compose restart`.
+
+Check that it connected:
+
+```bash
+ipfs swarm peers | grep 12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9
+```
+
+Peering here is one-way: the community node has no matching entry, so keeping the connection alive is your side's job. The [kubo config docs](https://github.com/ipfs/kubo/blob/master/docs/config.md#peering){target="_blank"} warn that one-way peering consumes connection resources on the other node, and that load concentrates on a single machine as the number of mirrors grows. Turn it on if you actually hit slow fetches, and skip this section if things already work.
+
 ## Maintenance and notes
 
 - **It keeps up automatically.** When the site changes its CID, the next scheduled run pins the new version and drops the old one. You do nothing.
-- **Disk use stays flat.** After unpinning the old version the script runs a garbage collection, so only the latest version takes space. The site is a plain static site and isn't large.
+- **Disk use stays flat.** After unpinning the old version the script runs a garbage collection, so only the latest version takes space. A full mirror is about 220 MB (measured August 2026).
 - **It won't lose the copy you have.** The script pins the new version successfully before dropping the old one, and keeps your existing copy if resolving or downloading fails.
 - **To stop helping:** unpin the current version and remove the schedule. It doesn't affect any other node.
 - **Privacy and risk:** what you pin is public documentation, so there's no privacy concern. Offering IPFS pinning carries different legal risk across jurisdictions, so weigh that for where you operate.
 
@@ -6,7 +6,7 @@ icon: simple/ipfs
 
 # :simple-ipfs: 帮忙 pin 文件站的 IPFS 镜像
 
-anoni.net 文件站除了主站，还有一份 IPFS 镜像，让文件在主站被封锁或下架时仍然读得到。IPFS 上的内容要有节点 pin 才会存活，目前只有社群自己的节点在 pin。你多架设一个节点帮忙 pin，网络上就多一份完整副本，抗删除的底气更足。
+anoni.net 文件站除了主站，还有一份 IPFS 镜像，让文件在主站被封锁或下架时仍然读得到。IPFS 上的内容要有节点 pin 才会存活，目前提供文件站内容的节点很少，社群自己那台是主力。你多架设一个节点帮忙 pin，网络上就多一份完整副本，抗删除的底气更足。
 
 这页教你用一个常驻的 IPFS 节点，加一支自动跟上最新版本的定时脚本。整个过程对 Windows、Linux、macOS 都适用，有没有用 Docker 都可以。
 
@@ -27,7 +27,19 @@ anoni.net 文件站除了主站，还有一份 IPFS 镜像，让文件在主站
 - IPNS（InterPlanetary Name System）是一个固定不变的名字，永远指向「目前最新」的那个 CID。文件站的 IPNS 名字就是下面那串 `k51…`。
 - pin 的意思是「保证留住某个 CID 的内容」。pin 绑在 CID 上，不会自己跟着 IPNS 走。所以文件站一发新版，你上次 pin 的还是旧 CID。
 
-结论就是这支脚本要做的事：先把 IPNS 换算成当前的 CID，再 pin 那个新 CID，然后放掉旧的。因为 CID 会变，这件事要定期重新执行，这就是为什么要设定时任务。
+结论就是这支脚本要做的事：先把 IPNS 换算成当前的 CID，再 pin 那个新 CID，然后放掉旧的。因为 CID 会变，换算与 pin 要定期重新执行，所以需要定时任务。
+
+### 三串标识符不要混用
+
+IPFS 上有三种长相接近的标识符，用途各自不同，贴错字段时工具会直接报错。
+
+| 标识符 | 开头 | 会不会变 | 用途 |
+|---|---|---|---|
+| CID | `bafybei…` | 每次发布都变 | 指定某一版内容 |
+| IPNS 名称 | `k51qzi…` | 固定 | 取得最新版，本页 pin 用这个 |
+| Peer ID | `12D3KooW…` | 固定 | 指定要连到哪一个节点 |
+
+pin 文件站只会用到 IPNS 名称。Peer ID 要到想让自己的节点跟社群节点保持固定连接时才用得上，做法见下面的〈进阶：跟社群节点保持常连〉。
 
 ## 运作原理（为什么定时就够，不用等通知）
 
@@ -38,6 +50,7 @@ anoni.net 文件站除了主站，还有一份 IPFS 镜像，让文件在主站
     文件站的 IPFS 坐标（公开值，可以直接用）：
 
     - IPNS 名称：`k51qzi5uqu5dlfm2jj0f70ex3r3babmwy8qh071inwknttr7wqa3uhdwvlmrmw`
+    - 节点 Peer ID：`12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9`（设定 peering 时才会用到）
     - 浏览器打开看：[https://anoni-net.ipns.dweb.link/](https://anoni-net.ipns.dweb.link/){target="_blank"}
 
 脚本每次执行的动作是：解析 IPNS 取得当前 CID，pin 新 CID，unpin 上次那版，回收空间。脚本先确认新版 pin 成功，才会放掉旧版。万一解析失败或抓不到内容，它会保留你手上现有的副本，不会让你的节点变空。
@@ -51,17 +64,25 @@ pin 要能抓齐内容，本机就得有一个持续运作的 IPFS daemon。下
     安装 [kubo](https://docs.ipfs.tech/install/command-line/){target="_blank"}（IPFS 官方的命令行版本）。macOS 可以用 Homebrew：
 
     ```bash
-    brew install ipfs
+    brew install kubo
     ```
 
+    Homebrew 的包名已从 `ipfs` 改为 `kubo`，旧名还是装得起来，但后面设定服务要用 `kubo` 这个名字。Intel 与 Apple Silicon 都支持。
+
     Linux 依 [官方说明](https://docs.ipfs.tech/install/command-line/){target="_blank"} 下载对应架构的 kubo。装好后初始化并启动 daemon：
 
     ```bash
     ipfs init          # 第一次才需要
     ipfs daemon
     ```
 
-    要让 daemon 长时间常驻，Linux 建议做成 systemd user service，macOS 可以用 `brew services` 或 launchd。临时测试时，直接让 `ipfs daemon` 在后台执行也可以。
+    要让 daemon 长时间常驻，Linux 建议做成 systemd user service。macOS 用 Homebrew 安装的话，包本身附了服务定义，一行就会常驻并在登录时自动启动：
+
+    ```bash
+    brew services start kubo
+    ```
+
+    临时测试时，直接让 `ipfs daemon` 在后台执行也可以。
 
 === "Windows"
 
@@ -184,10 +205,34 @@ ipfs pin ls --type=recursive | grep "${CID#/ipfs/}"
 
 也可以在本机 gateway 打开看，内容正常显示就成功了：`http://127.0.0.1:8080${CID}/`。Docker 用户把上面的 `ipfs` 换成 `docker exec ipfs_host ipfs`。
 
+## 进阶：跟社群节点保持常连（选用）
+
+pin 只靠 IPNS 名称就能完成，内容交给 DHT 去找。第一次要把整份镜像抓齐，碰上 DHT 查询慢或查不到的时候会拖很久。想让自己的节点跟来源节点维持固定连接，可以设定 kubo 的 peering。
+
+编辑 `~/.ipfs/config`，在最外层加入 `Peering` 区块：
+
+```json
+"Peering": {
+  "Peers": [
+    { "ID": "12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9" }
+  ]
+}
+```
+
+`Addrs` 可以省略，kubo 会自己向 DHT 查地址。改完重启 daemon 生效。Docker 用户要改的是 `./ipfs-data/config`，接着执行 `docker compose restart`。
+
+确认连上了：
+
+```bash
+ipfs swarm peers | grep 12D3KooWEzvBhnLa6NZnjnw22Yoqs56xq4pNCZdkkxw5yxvi1eV9
+```
+
+peering 是单向设定，社群节点那端没有对应条目，连接的保活责任落在你这边。[kubo 官方文档](https://github.com/ipfs/kubo/blob/master/docs/config.md#peering){target="_blank"} 提醒过，单向 peering 会占用对方节点的连接资源，镜像数量变多之后负担会集中在同一台。建议实际遇到抓取不顺再开，平常运作正常就跳过。
+
 ## 维护与注意事项
 
 - **会自动跟上新版**：文件站换 CID 后，下一次定时任务就会 pin 新版、放掉旧版，你不用做任何事。
-- **硬盘不会一直变大**：脚本 unpin 旧版后会执行一次垃圾回收，只留最新版本占空间。文件站是纯静态网站，体积不大。
+- **硬盘不会一直变大**：脚本 unpin 旧版后会执行一次垃圾回收，只留最新版本占空间。一份完整镜像约 220 MB（2026 年 8 月实测）。
 - **不会弄丢你手上的版本**：脚本先确认新版 pin 成功才放掉旧版，解析或下载失败时会保留现有副本。
 - **想停止帮忙**：unpin 目前版本、把定时任务移除即可，不影响其他节点。
 - **隐私与风险**：你 pin 的是公开文件，没有隐私顾虑。提供 IPFS pin 在不同司法管辖下的风险不同，相关限制见 [去中心化网站发布](../advanced/dweb-ipfs-onion.md) 的「已知限制与风险」。