kurihada/notebook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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 月)
This commit is contained in:
kurihada
2026-06-04 11:58:36 +08:00
parent 155b347d3f
commit 88967a238f
15 changed files with 295 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/3D打印/index.md
+7 -3
View File
@@ -11,9 +11,13 @@
## 📦 模型 & 项目
> 还没有内容。看到感兴趣的模型、打印了什么东西，可以告诉 Claude 帮你记录。
>
> 比如：「帮我在 3D打印里加一条，打印了 Genji 盔甲模型，链接是...，参数是...」
> 还没有内容，待补充。计划记录：
> - 已打印模型列表（名称、链接、耗材、耗时）
> - 打印参数优化笔记（层高、温度、回抽、支撑）
> - 耗材测试记录（PLA / PETG / ABS 不同品牌对比）
> - Bambu Lab A1 维护日志
看到感兴趣的模型、打印了什么东西，可以告诉 Claude 帮你记录。
---
docs/index.md
+10 -1
View File
@@ -22,14 +22,23 @@ comments: false
## 🔗 快捷入口
- **照片管理**：[Immich](http://localhost:2283)（AI 标签、人脸识别、RAW 预览）
- **照片管理**：[Immich](https://photo.kurihada.com)（AI 标签、人脸识别、RAW 预览）
- **大疆素材**：`~/action5pro/`
- **RAW 原片**：`~/aa/`
---
## 💬 反馈
页面底部有评论区（[Artalk](技术/artalk评论系统.md) 自托管），欢迎对内容进行提问、补充或指正。
可以使用顶部搜索栏（右上角 🔍）快速查找内容。
---
## 🛠 本站说明
- 基于 [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) 构建
- 所有内容为纯 Markdown 文件，存储在 `~/kb/docs/`
- Claude 协助维护和更新内容
- 评论系统 [Artalk](技术/artalk评论系统.md) 自托管，数据存储在本站服务器
docs/技术/artalk评论系统.md
+7 -4
View File
@@ -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`。修改配置时建议**两边保持一致**，避免排查困难。
docs/技术/immich部署.md
+70
View File
@@ -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
```
docs/技术/index.md
+18 -11
View File
@@ -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）
docs/技术/mkdocs部署.md
+33 -4
View File
@@ -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 # 零停机
```
---
docs/技术/旁路由使用/Android.md
+13 -6
View File
@@ -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 是否在线
docs/技术/旁路由使用/Linux.md
+47 -5
View File
@@ -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 # 重启翻墙
docs/技术/旁路由使用/Windows.md
+1 -1
View File
@@ -38,7 +38,7 @@
4. 点击 **保存**
?> 不需要翻墙时关掉即可，国内网站直连，不受影响。
!!! tip "不需要翻墙时关掉即可，国内网站直连，不受影响。"
---
docs/技术/旁路由使用/macOS.md
+3 -3
View File
@@ -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 去广告
docs/技术/旁路由部署.md
+52 -6
View File
@@ -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 和代理才能使用旁路由。每个平台的设置方式不同，详见各平台使用指南：
docs/摄影/index.md
+8 -4
View File
@@ -14,12 +14,16 @@
| 内容 | 位置 | 大小 |
|------|------|------|
| RAW 原片 (ARW) | `~/aa/` | 117 张 / 2.8 GB |
| Immich 管理 | [Immich](http://localhost:2283) | — |
| Immich 管理 | [Immich](https://photo.kurihada.com) | AI 标签 + RAW 预览 |
---
## 📝 拍摄笔记
> 还没有内容，待 Claude 帮你整理。
>
> 可以告诉 Claude：「帮我写一篇 xx 拍摄的笔记，参数是...」
> 还没有内容，待补充。计划涵盖：
> - 拍摄参数记录（光圈、快门、ISO、焦段）
> - 后期思路（Lightroom / Darktable 调色）
> - 航拍飞行点位与构图笔记
> - 赛里木湖之行的拍摄成果（2026 年 8 月）
可以告诉 Claude：「帮我写一篇 xx 拍摄的笔记，参数是...」
docs/旅行/index.md
+3 -1
View File
@@ -4,7 +4,9 @@
## 📝 游记 & 计划
> 还没有内容，待 Claude 帮你整理。
- **[赛里木湖 2026](赛里木湖2026.md)** — 8 月 20-25 日，6 天北疆赛里木湖 + 独库公路，含拍摄计划与行程表
> 更多游记待补充。8 月赛里木湖之行的旅行日记将在行程中或结束后更新。
---
docs/日记/index.md
+18 -3
View File
@@ -2,6 +2,21 @@
---
> 日记按日期组织，文件名格式：`YYYY-MM-DD.md`
>
> 告诉 Claude 你想记录什么，我来帮你写成结构化的日记。
## 使用方式
日记按日期组织，文件名格式 `YYYY-MM-DD.md`。
告诉 Claude：「帮我记一下今天的日记，今天做了...」
## 日记列表
> 还没有日记条目，待添加。
---
## 计划记录
- 技术折腾日志（部署了什么东西、踩了什么坑）
- 旅行当天的即时记录
- 摄影外出拍摄日志
- 日常碎碎念
mkdocs.yml
+5 -9
View File
@@ -61,22 +61,18 @@ extra:
nav:
- 首页: index.md
- 旅行:
- 旅行/index.md
- 赛里木湖 2026: 旅行/赛里木湖2026.md
- 摄影:
- 摄影/index.md
- 摄影: 摄影/index.md
- 技术:
- 技术/index.md
- MkDocs 部署: 技术/mkdocs部署.md
- 旁路由部署: 技术/旁路由部署.md
- Artalk 评论系统: 技术/artalk评论系统.md
- Immich 照片管理: 技术/immich部署.md
- 旁路由部署: 技术/旁路由部署.md
- 旁路由使用:
- Linux: 技术/旁路由使用/Linux.md
- Windows: 技术/旁路由使用/Windows.md
- macOS: 技术/旁路由使用/macOS.md
- Android: 技术/旁路由使用/Android.md
- iPhone: 技术/旁路由使用/iPhone.md
- 3D打印:
- 3D打印/index.md
- 日记:
- 日记/index.md
- 3D打印: 3D打印/index.md
- 日记: 日记/index.md