fix: 全面修订技术文档 — 修复 P0/P1/P2 共 16 项审查问题

P0（必须修复）: - 技术/index.md: Web 服务 NPM → Caddy，补充服务列表和域名 - 旁路由部署.md: VPS OS CentOS → Debian，补全安装命令 - 旁路由部署.md: 新增 systemd-resolved DNS 端口冲突解决步骤 - mkdocs.yml: 删除冗余 index.md 子项，空分类用简单链接 - artalk评论系统.md: docker-compose.yml 补全环境变量 P1（建议修复）: - Linux.md: 区分旁路由本机 vs 局域网其他机器两种场景 - Android.md: 移除不支持的 Clash Meta，添加私人 DNS 冲突警告 - macOS.md: 终端命令补注视说明占位符需替换 - 旅行/index.md: 添加赛里木湖 2026 游记链接 - mkdocs部署.md: 补充 Docker 网络创建、首次启动、LE 邮箱配置 - artalk评论系统.md: 修正环境变量与配置文件矛盾说明 P2（优化）: - 首页: 添加评论区说明、修正 Immich 链接为公网域名 - 旁路由部署.md: 加固有章节目录（无锚点纯文本） - 摄影/3D打印/日记 index.md: 充实引导内容 - 新增 Immich 部署文档 - 统一 callout 风格: ?> 改为 !!! tip - GitHub Stars 加时间限定 (截至 2026 年 6 月)
2026-06-04 11:58:36 +08:00
parent 155b347d3f
commit 88967a238f
15 changed files with 295 additions and 61 deletions
@@ -13,7 +13,7 @@
 - **轻量**：服务器资源有限，不能上 PostgreSQL 等重型依赖
 - **中文友好**：面向中文用户

-对比了 3 款主流的自托管评论系统：
+对比了 3 款主流的自托管评论系统（数据截至 2026 年 6 月）：

 | | Artalk | Waline | Twikoo |
 |------|:---:|:---:|:---:|
@@ -91,6 +91,9 @@ services:
    environment:
      - TZ=Asia/Shanghai
      - ATK_LOCALE=zh-CN
+      - ATK_SITE_DEFAULT=我的知识库
+      - ATK_SITE_URL=https://note.kurihada.com
+      - ATK_TRUSTED_DOMAINS=https://note.kurihada.com
    networks:
      - nginx

@@ -99,7 +102,7 @@ networks:
    external: true
 ```

-> 注意：需要加入 `nginx` 网络以便 Caddy 能通过容器名 `artalk` 访问。
+> 注意：需要加入 `nginx` 网络以便 Caddy 能通过容器名 `artalk` 访问。`ATK_TRUSTED_DOMAINS` 限制允许跨域请求的域名，防止 CSRF。

 ### 1.3 启动

@@ -261,6 +264,6 @@ docker exec -it artalk ./artalk admin

 `artalk.yml` 由 Docker 挂载后属主为 root，本地编辑需 `sudo`。修改后需 `docker restart artalk` 才能生效。

-### 环境变量不一定映射到配置
+### 环境变量与配置文件的关系

-Docker Compose 中设置的 `ATK_SITE_DEFAULT`、`ATK_SITE_URL` 等环境变量不一定能覆盖 `artalk.yml` 中的值（取决于 Artalk 版本）。建议直接编辑 `artalk.yml` 确保生效。
+Artalk 2.9.x 中环境变量和 `artalk.yml` 均可生效。当前部署两种方式同时使用，`ATK_SITE_DEFAULT`、`ATK_SITE_URL` 在 docker-compose.yml 中设置，同时也直接写入了 `artalk.yml`。修改配置时建议**两边保持一致**，避免排查困难。
@@ -0,0 +1,70 @@
+# Immich 照片管理
+
+> 自托管照片管理服务，支持 AI 标签、人脸识别、RAW 预览、多用户。域名 `photo.kurihada.com`。
+
+---
+
+## 架构
+
+Immich 由 4 个容器组成，部署在 `~/docker/immich/`：
+
+| 容器 | 镜像 | 说明 |
+|------|------|------|
+| immich_server | ghcr.io/immich-app/immich-server | 主服务 + API |
+| immich_postgres | pgvector/pgvector | 数据库（PostgreSQL + pgvector） |
+| immich_redis | valkey/valkey | 缓存 |
+| immich_machine_learning | ghcr.io/immich-app/immich-machine-learning | AI 智能搜索/人脸识别 |
+
+通过 Caddy 反代 `photo.kurihada.com → immich_server:2283`。
+
+---
+
+## 日常管理
+
+```bash
+# 查看状态
+cd ~/docker/immich && docker compose ps
+
+# 查看日志
+docker logs immich_server -f
+
+# 更新
+docker compose pull && docker compose up -d
+
+# 完整重启
+docker compose down && docker compose up -d
+```
+
+---
+
+## 存储
+
+| 内容 | 路径 |
+|------|------|
+| 照片库 | `~/docker/immich/library/` |
+| 数据库 | PostgreSQL（容器内） |
+| 外部库（RAW） | `~/aa/`（只读挂载，Immich 索引访问） |
+
+---
+
+## 备份
+
+```bash
+# 备份照片库
+rsync -av ~/docker/immich/library/ /backup/immich-library/
+
+# 备份数据库（推荐用 pg_dump）
+docker exec immich_postgres pg_dump -U postgres immich > /backup/immich-db-$(date +%Y%m%d).sql
+```
+
+---
+
+## 更新
+
+Immich 发版频繁（~每月），更新前务必查看 [Release Notes](https://github.com/immich-app/immich/releases) 了解破坏性变更。
+
+```bash
+cd ~/docker/immich
+docker compose pull
+docker compose up -d
+```
@@ -8,7 +8,8 @@
 |------|------|
 | 系统 | Ubuntu 24.04, 16 核, 12GB RAM |
 | 存储 | 1TB NVMe SSD（后续加机械硬盘） |
-| Web 服务 | Nginx Proxy Manager (Docker) |
+| 反向代理 | Caddy (Docker) |
+| Docker 网络 | `nginx`（所有服务加入此网络互通） |
 | 内网穿透 | frpc |
 | 照片管理 | Immich |
 | 知识库 | MkDocs Material |
@@ -17,20 +18,26 @@

 ## 📋 服务列表

-| 服务 | 说明 |
-|------|------|
-| Immich | 照片/视频管理 + AI 标签 |
-| Immich API | Immich 后端 API |
-| Nginx Proxy Manager | 反向代理管理面板 |
-| Gitea | 自托管 Git 服务 |
-| Minio | S3 兼容对象存储 |
-| Java app.jar | Spring Boot 应用 |
-| Java auth-backend | 认证后端 |
+所有公网流量经 Caddy（TLS 终结）转发到各后端服务。
+
+| 服务 | 域名 | 说明 |
+|------|------|------|
+| Caddy | — | 反向代理，自动 Let's Encrypt TLS |
+| MkDocs | [note.kurihada.com](https://note.kurihada.com) | 知识库（本页面） |
+| Artalk | 同域 `/artalk/` | 评论系统 |
+| Immich | [photo.kurihada.com](https://photo.kurihada.com) | 照片/视频管理 + AI 标签 |
+| Gitea | [git.kurihada.com](https://git.kurihada.com) | 自托管 Git 服务 |
+| MinIO | [minio.kurihada.com](https://minio.kurihada.com) | S3 兼容对象存储 |
+| Alist | [pan.kurihada.com](https://pan.kurihada.com) | 网盘文件管理 |
+| Vaultwarden | [pass.kurihada.com](https://pass.kurihada.com) | 密码管理器 |
+| WordPress | [www.kurihada.com](https://www.kurihada.com) | 博客 |

 ---

 ## 📝 技术笔记

 - [MkDocs 知识库部署](mkdocs部署.md) — MkDocs Material 构建 + Caddy 静态文件服务
- [旁路由 + 去广告 部署](旁路由部署.md) — sing-box + AdGuard Home 旁路由架构、配置路径、已知问题
 - [Artalk 评论系统](artalk评论系统.md) — 自托管评论系统，Docker 部署 + MkDocs 集成
+- [Immich 照片管理](immich部署.md) — 自托管照片服务，AI 标签 + 人脸识别
+- [旁路由部署](旁路由部署.md) — sing-box + AdGuard Home 架构、部署、踩坑笔记
+- [旁路由使用指南](旁路由使用/Linux.md) — 各平台客户端配置（Linux / Windows / macOS / Android / iPhone）
@@ -100,7 +100,15 @@ git commit -m "描述改动"      # 提交 Markdown 源码

 ## 三、Caddy 部署

-### 3.1 docker-compose.yml
+### 3.1 前置：创建 Docker 网络
+
+```bash
+docker network create nginx
+```
+
+所有通过 Caddy 反代的服务都加入 `nginx` 网络，容器间通过容器名互相访问。
+
+### 3.2 docker-compose.yml

 Caddy 部署在 `~/docker/caddy/`：

@@ -125,7 +133,25 @@ networks:
    external: true
 ```

-### 3.2 Caddyfile 中 kb 的配置
+### 3.3 首次启动
+
+```bash
+cd ~/docker/caddy && docker compose up -d
+```
+
+启动前确认 `~/kb/site/` 目录存在（需先执行过 `mkdocs build`），否则 bind mount 会创建一个空目录导致 404。
+
+### 3.4 Caddyfile 中 kb 的配置
+
+Caddyfile 开头有全局块配置 Let's Encrypt 通知邮箱：
+
+```caddy
+{
+    email kurihada@qq.com
+}
+```
+
+kb 站点的配置：

 ```caddy
 note.kurihada.com {
@@ -146,10 +172,13 @@ note.kurihada.com {
 - `handle { ... }` — 包裹 `file_server`，保证和 `handle_path` 互斥
 - Caddy 自动申请和续期 Let's Encrypt TLS 证书，无需额外配置

-### 3.3 部署后重载
+### 3.5 部署后重载
+
+修改 Caddyfile 后重载（两种方式）：

 ```bash
-docker restart caddy
+docker restart caddy                        # 简单粗暴，短暂中断
+docker exec caddy caddy reload --config /etc/caddy/Caddyfile  # 零停机
 ```

 ---
@@ -27,7 +27,7 @@

 4. 保存

-?> 不同 Android 厂商设置路径略有差异，核心就是 WiFi → 高级 → 静态 IP + 手动代理。
+!!! tip "不同 Android 厂商设置路径略有差异，核心就是 WiFi → 高级 → 静态 IP + 手动代理。切换静态 IP 时，**IP 地址/网关/子网掩码保持 DHCP 分配的值不变**，只修改 DNS 字段。"

 ---

@@ -37,11 +37,12 @@

 ### 推荐 App

-| App | 价格 | 说明 |
-|-----|:---:|------|
-| **Hiddify Next** | 免费 | 开源，支持 VLESS Reality |
-| **v2rayNG** | 免费 | 老牌客户端，功能全面 |
-| **Clash Meta** | 免费 | 规则灵活 |
+| App | 价格 | VLESS Reality |
+|-----|:---:|:---:|
+| **Hiddify Next** | 免费 | 支持 |
+| **v2rayNG** | 免费 | 支持 |
+
+> Clash Meta 虽然规则灵活，但**不支持 VLESS Reality**，不适合此旁路由架构。

 ### 配置方法

@@ -75,6 +76,12 @@

 有些 app（如银行类）不走系统代理。可以在 Hiddify Next 等 App 中使用 **VPN 模式**，接管全部流量。

+### DNS 去广告不生效？
+
+Android 9+ 有「私人 DNS」（DNS-over-TLS）功能，开启后会**覆盖 WiFi 的 DNS 设置**，导致 AdGuard Home 被绕过。
+
+检查路径：**设置 → 连接 → 更多连接设置 → 私人 DNS → 设为关闭**
+
 ### 出门时无法连接 VPS？

 1. 检查 VPS 是否在线
@@ -6,9 +6,13 @@

 ## 接入旁路由

-### 系统代理（GNOME）
+根据你的 Linux 机器是不是旁路由本身，选择对应的配置方式。

-1. 打开 **设置 → 网络 → 代理**
+### 场景 A：这台 Linux 就是旁路由
+
+本机已运行 sing-box + AdGuard Home，DNS 和代理指向自己即可。
+
+1. 打开 **设置 → 网络 → 代理**（GNOME）或者用 NetworkManager 命令行
 2. 选择 **手动**
 3. 填写：

@@ -17,14 +21,51 @@
 | SOCKS 代理 | `127.0.0.1` |
 | 端口 | `7890` |

-?> DNS 会自动使用 AdGuard（因为旁路由本机 DNS 已设为 `127.0.0.1`）。
+!!! tip "DNS 会自动使用 AdGuard（旁路由本机 DNS 已设为 `127.0.0.1`），无需额外配置。"

-### 终端代理（可选）
+### 场景 B：这台 Linux 是局域网内其他机器
+
+DNS 和代理都需要指向旁路由 IP。
+
+#### 设置 DNS
+
+**GNOME 图形界面：**
+
+1. 打开 **设置 → 网络**
+2. 选择当前连接 → **IPv4 → DNS**
+3. 添加：`旁路由 IP`（如 `192.168.31.112`）
+4. 备用：`223.5.5.5`
+
+**命令行方式（NetworkManager）：**
+
+```bash
+nmcli con mod "连接名" ipv4.dns "旁路由IP" ipv4.ignore-auto-dns yes
+nmcli con up "连接名"
+```
+
+#### 设置系统代理
+
+1. 打开 **设置 → 网络 → 代理**
+2. 选择 **手动**
+3. 填写 SOCKS 代理地址为旁路由 IP
+
+| 字段 | 值 |
+|------|-----|
+| SOCKS 代理 | `旁路由 IP`（如 `192.168.31.112`） |
+| 端口 | `7890` |
+
+---
+
+## 终端代理（可选）

 如果需要在终端里走代理，设置环境变量：

 ```bash
+# 本机就是旁路由
 export ALL_PROXY=socks5://127.0.0.1:7890
+
+# 局域网内其他机器（替换为实际 IP）
+export ALL_PROXY=socks5://旁路由IP:7890
 ```

 或者写入 `~/.bashrc` 持久化：
@@ -48,13 +89,14 @@ curl --socks5 127.0.0.1:7890 https://www.google.com -o /dev/null -s -w '%{http_c
 # 测试 DNS 去广告
 nslookup doubleclick.net
 # 返回 0.0.0.0 → 广告域名已被拦截
+# 如果提示 command not found，安装 dnsutils（Debian/Ubuntu）或 bind-utils（Fedora）
 ```

 ---

 ## 服务管理

-旁路由本机就是服务器，所以日常管理命令也在这里执行：
+如果这台机器就是旁路由，日常管理命令：

 ```bash
 sudo systemctl restart sing-box     # 重启翻墙
@@ -38,7 +38,7 @@

 4. 点击 **保存**

-?> 不需要翻墙时关掉即可，国内网站直连，不受影响。
+!!! tip "不需要翻墙时关掉即可，国内网站直连，不受影响。"

 ---

@@ -38,14 +38,14 @@

 4. 点击 **好**

-?> 不需要翻墙时关掉即可。也可以使用 **SwitchyOmega**（Chrome 扩展）按规则自动切换，国内网站不走代理。
+!!! tip "不需要翻墙时关掉即可。也可以使用 **SwitchyOmega**（Chrome 扩展）按规则自动切换，国内网站不走代理。"

 ---

 ## 终端代理（可选）

 ```bash
-# 临时开启
+# 临时开启（替换为实际旁路由 IP，如 192.168.31.112）
 export ALL_PROXY=socks5://旁路由IP:7890

 # 写入 ~/.zshrc 持久化
@@ -59,7 +59,7 @@ echo 'alias unproxy="unset ALL_PROXY"' >> ~/.zshrc

 ```bash
 # 测试代理是否通
-curl --socks5 旁路由IP:7890 https://www.google.com -o /dev/null -s -w '%{http_code}'
+curl --socks5 旁路由IP:7890 https://www.google.com -o /dev/null -s -w '%{http_code}'   # 替换为实际 IP
 # 返回 200 → 正常

 # 测试 DNS 去广告
@@ -2,6 +2,20 @@

 > 用一台 Ubuntu 机器做旁路由，实现全家翻墙 + DNS 去广告。基于 sing-box（VLESS + Reality）和 AdGuard Home。

+## 目录
+
+1. **概述** — 什么是旁路由、架构图
+2. **一、部署教程** — 6 步完成旁路由搭建
+   - 1.1 前置条件
+   - 1.2 本机网络配置（静态 IP、IP 转发）
+   - 1.3 VPS 服务端（sing-box 安装、Reality 配置）
+   - 1.4 本机客户端（sing-box 入站 + 路由规则）
+   - 1.5 DNS 端口冲突解决（systemd-resolved）
+   - 1.6 AdGuard Home（Docker 部署、过滤规则）
+   - 1.7 各设备接入
+3. **二、使用教程** — 日常管理、故障排查
+4. **三、踩坑笔记** — TProxy 为什么不用、DNS 劫持等
+
 ---

 ## 概述
@@ -52,7 +66,7 @@ graph TD
 ### 1.1 前置条件

 - 一台 24 小时开机的 Linux 设备（本例 Ubuntu 24.04），已接入局域网
- 一台境外 VPS（本例香港 CentOS Stream 9）
+- 一台境外 VPS（本例 Debian 12，位于香港）
 - 一个域名（用于 Reality 伪装，本例 `www.microsoft.com` 作为 SNI）

 ### 1.2 步骤一：配置旁路由本机网络
@@ -97,12 +111,22 @@ sudo sysctl -p /etc/sysctl.d/99-bypass.conf
 #### 安装 sing-box

 ```bash
-# VPS 上执行（CentOS Stream 9 示例）
-# 官方安装脚本
+# VPS 上执行（Debian 12，其他发行版参见官方文档）
+# 安装依赖
+sudo apt update && sudo apt install -y curl ca-certificates
+
+# 添加官方源
+sudo mkdir -p /etc/apt/keyrings
 curl -fsSL https://sing-box.app/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/sing-box.gpg
-# 具体安装方式参见 https://sing-box.sagernet.org/installation/
+echo "deb [signed-by=/etc/apt/keyrings/sing-box.gpg] https://sing-box.app/deb /" | sudo tee /etc/apt/sources.list.d/sing-box.list
+
+# 安装并启用
+sudo apt update && sudo apt install -y sing-box
+sudo systemctl enable sing-box
 ```

+> 其他发行版（CentOS/Fedora）的安装方式参见 [sing-box 官方文档](https://sing-box.sagernet.org/installation/)。
+
 #### 生成 Reality 密钥

 ```bash
@@ -243,7 +267,29 @@ curl --socks5 127.0.0.1:7890 https://www.google.com -o /dev/null -s -w '%{http_c
 # 返回 200 或 301/302 即成功
 ```

-### 1.5 步骤四：部署 AdGuard Home
+### 1.5 步骤四：解决 DNS 端口冲突
+
+Ubuntu 24.04 默认运行 `systemd-resolved`，占用 `127.0.0.53:53`。AdGuard Home 需要绑定 `0.0.0.0:53`，必须先释放 53 端口：
+
+```bash
+# 禁用 systemd-resolved 的 DNS stub listener
+sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
+sudo systemctl restart systemd-resolved
+
+# 确认 53 端口已释放（应该无输出）
+sudo ss -tuln | grep ':53 '
+```
+
+> 如果 `ss` 命令仍有输出（说明其他进程占用 53 端口），用 `sudo lsof -i :53` 排查。
+
+同时确保 `/etc/resolv.conf` 指向有效的 DNS 服务器：
+
+```bash
+# 如果 /etc/resolv.conf 指向 127.0.0.53，暂时改为公共 DNS
+echo 'nameserver 223.5.5.5' | sudo tee /etc/resolv.conf
+```
+
+### 1.6 步骤五：部署 AdGuard Home

 用 Docker 启动 AdGuard Home，统一管理局域网 DNS 并过滤广告。

@@ -297,7 +343,7 @@ docker run -d \
 https://dns.quad9.net/dns-query
 ```

-### 1.6 步骤五：各设备接入
+### 1.7 步骤六：各设备接入

 部署完成后，各终端设备需要配置 DNS 和代理才能使用旁路由。每个平台的设置方式不同，详见各平台使用指南：