ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto-sync: 2026-04-22 08:02

Browse Source
This commit is contained in:
weishen
2026-04-22 08:02:59 +08:00
parent de096f2f88
commit 143d1fd105
62 changed files with 5232 additions and 1268 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
wiki/concepts/BI平台.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: "BI平台"
type: concept
aliases:
- BI Platform
- Business Intelligence Platform
- 数据分析平台
tags: [bi, data, visualization, analytics]
date: 2026-04-14
---
# BI平台
## Definition
**BI 平台**（Business Intelligence Platform）是一种软件系统，用于从企业数据中提取洞察、支持决策制定。核心功能包括：数据连接与整合、SQL 查询与探索、多样化图表可视化、交互式仪表盘构建、数据驱动报警。
## Key Capabilities
1. **多数据源连接**: 支持 SQL 数据库、API、文件导入等多种数据源
2. **SQL 探索**: 内置 SQL 查询编辑器，支持即席分析
3. **图表可视化**: 提供折线图、柱状图、饼图、地理图、热力图等多样化图表
4. **仪表盘构建**: 将多个图表组合为仪表盘，支持筛选和交互
5. **权限管理**: 基于角色的访问控制（RBAC）
## Wiki 中的相关工具
| 工具 | 类型 | 特点 | 部署方式 |
|------|------|------|----------|
| [[Apache Superset]] | BI 平台 | Apache 基金会项目，SQL 优先，图表 Gallery 丰富 | Docker |
| [[Grafana]] | 监控/仪表盘 | 监控数据可视化首选，支持告警 | Docker |
| [[Jellyfin]] | 媒体服务器 | 视频播放管理，非 BI | Docker |
## Key Distinction: BI vs 监控
- **BI 平台**：面向业务分析（销售/财务/运营），强调交互式探索和美观的图表 Gallery
- **监控平台**（如 Grafana）：面向系统可靠性（CPU/内存/服务可用性），强调告警和时序数据
- 两者在仪表盘层面有重叠，Superset 可以接入 Prometheus 等监控数据源
## Related Concepts
- [[数据可视化]]
- [[Docker容器化部署]]
- [[Home Server Automation]]

68
wiki/concepts/DNS托管.md Normal file
View File

@@ -0,0 +1,68 @@
# DNS托管
> DNS托管，通过 Cloudflare 免费托管 ishenwei.online 域名 DNS 解析，提供全球 CDN 和免费 SSL 证书。
## Overview
Cloudflare 是全球知名的 CDN 和 DNS 服务提供商，提供免费的 DNS 托管服务。本方案使用 Cloudflare 托管 ishenwei.online 主域名，通过 A 记录将子域名指向 RackNerd VPS 公网 IP（192.227.222.142），配合 Caddy 实现基于域名的反向代理。
## Configuration
|| 记录类型 | 主机名 | 指向 | 说明 |
|---------|---------|-------|------|------|
| A | vps.ishenwei.online | 192.227.222.142 | VPS 直连 |
| A | *.ishenwei.online | 192.227.222.142 | 所有子域名泛解析 |
| A | macmini.ishenwei.online | 192.227.222.142 | Mac Mini |
| A | nas.ishenwei.online | 192.227.222.142 | Synology NAS |
| A | ubuntu1.ishenwei.online | 192.227.222.142 | Ubuntu Server 1 |
| A | ubuntu2.ishenwei.online | 192.227.222.142 | Ubuntu Server 2 |
## Free Features Used
1. **DNS 解析**：全球 200+ 节点，毫秒级解析
2. **免费 SSL 证书**：通用加密模式（Flexible SSL），Caddy 提供服务端证书
3. **CDN 加速**：静态资源全球缓存
4. **DDoS 防护**：基础 DDoS 防护免费
5. **HTTP/2 + HTTP/3**：现代协议支持
## Traffic Flow
```
[用户浏览器]
│
│ DNS 查询: grafana.ishenwei.online
▼
[Cloudflare DNS]
A 记录 → 192.227.222.142
│
│ HTTPS 请求
▼
[RackNerd VPS: Caddy]
TLS 终止 + 反向代理
│
│ FRP 隧道
▼
[内网服务]
```
## vs 阿里云 DNS
- **阿里云 DNS**：收费（按解析量），功能全面，适合国内业务
- **Cloudflare**：免费，功能对个人使用足够，全球节点更多，隐私保护更好
## DNS-01 Challenge (Wildcard Certificate)
申请 *.ishenwei.online 泛域名证书时，Let's Encrypt 通过 DNS-01 挑战验证域名所有权：
1. CA 要求在 `_acme-challenge.ishenwei.online` TXT 记录写入特定值
2. Cloudflare API 自动更新该 TXT 记录
3. CA 验证通过后颁发泛域名证书
## Related Concepts
- [[HTTPS自动化证书]] — Caddy 自动申请 Let's Encrypt 证书
- [[反向代理]] — Caddy 基于域名的反向代理
- [[内网穿透]] — FRP 隧道传输
- [[CDN]] — Cloudflare 全球内容分发网络
## Related Entities
- [[Cloudflare]] — DNS 托管服务商
- [[RackNerd]] — VPS 公网 IP（DNS A 记录指向）
- [[Caddy]] — 自动 HTTPS + 反向代理
- [[FRP]] — 内网穿透隧道
- [[阿里云 DNS]] — 国内 DNS 替代方案

14
wiki/concepts/Docker-Compose.md
View File

@@ -42,9 +42,23 @@ services:
## Used By
- [[用docker安装it-tools]]
- [[用docker安装transmission]]
- [[如何删除旧的废弃的docker-container-volume]]
- [[Navidrome]]
- [[Jellyfin]]
- [[RSSHub]]
- [[Portainer]]
## External Mode
Compose 文件中声明 `external: true` 可让 Docker 复用已存在的 Volume 或 Network 而非创建新的，避免重装时的命名冲突警告：
```yaml
volumes:
portainer_data:
external: true
networks:
portainer_network:
external: true
```
## Related Concepts
- [[Docker-Image]]

113
wiki/concepts/Docker堆栈.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Docker堆栈
type: concept
tags: [docker, compose, orchestration]
date: 2025-12-29
---
# Docker堆栈
## Definition
Docker 堆栈（Docker Stack）是指通过 Docker Compose 编排的多容器应用，由多个相互依赖的服务组成，共同提供完整功能。在 [[Zipline]] 图床方案中，MinIO + PostgreSQL + Zipline 构成一个完整的堆栈。
## Zipline Stack Architecture
```yaml
services:
minio: # S3 兼容存储
image: minio/minio:latest
depends_on: []
postgres: # 元数据库
image: postgres:16
depends_on: []
zipline: # 图床应用
image: ghcr.io/diced/zipline:latest
depends_on:
minio:
condition: service_healthy
postgres:
condition: service_healthy
```
## Service Dependency Patterns
### Pattern 1: Simple depends_on
```yaml
service_a:
depends_on:
- service_b
```
仅确保启动顺序，不等待就绪。
### Pattern 2: Health Check + Condition（本方案推荐）
```yaml
service_b:
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/health"]
interval: 30s
retries: 3
service_a:
depends_on:
service_b:
condition: service_healthy
```
确保依赖服务就绪后才启动，避免竞态条件。
### Pattern 3: wait-for Script
```bash
#!/bin/bash
wait-for-it.sh service:port -- echo "Service is ready"
```
## Key Compose Features Used
| 功能 | 配置 | 说明 |
|------|------|------|
| 健康检查 | `healthcheck` | 自动检测服务状态 |
| 条件依赖 | `condition: service_healthy` | 等待健康检查通过 |
| 资源限制 | `deploy.resources.limits` | 防止单服务耗尽资源 |
| 重启策略 | `restart: unless-stopped` | 异常自动重启 |
| 端口映射 | `ports` | 暴露服务端口 |
| 卷挂载 | `volumes` | 数据持久化 |
## Resource Limits in This Stack
| 服务 | 内存限制 | 说明 |
|------|----------|------|
| MinIO | 1G | S3 存储，缓存友好 |
| PostgreSQL | 512M | 元数据，索引优先 |
| Zipline | 512M | Node.js，适中即可 |
## Volume Persistence
| 卷路径 | 内容 | 备份策略 |
|--------|------|----------|
| `/volume1/docker/zipline-stack/minio/minio_data` | 图片文件 | Synology Hyper Backup |
| `/volume1/docker/zipline-stack/zipline/pg_data` | 数据库文件 | **不要直接备份**（见下） |
### Important: Database Volume Warning
> **警告**：不要直接备份 PostgreSQL 数据目录（`/var/lib/postgresql/data`）
>
> 热备份运行中的数据库目录会导致数据损坏。应使用 `pg_dump` 逻辑备份。
正确方式：
```bash
# 使用 pg_dump 逻辑备份（热备份，安全）
docker exec zipline_postgres pg_dump -U zipline -d zipline | gzip > backup.sql.gz
```
## Connections
- [[MinIO]] ← part of ← [[Docker堆栈]]
- [[PostgreSQL]] ← part of ← [[Docker堆栈]]
- [[Zipline]] ← part of ← [[Docker堆栈]]
- [[群晖 NAS]] ← hosts ← [[Docker堆栈]]
## Related Concepts
- [[Docker Compose]]
- [[容器资源限制]]
- [[容器重启策略]]
- [[逻辑备份]]

143
wiki/concepts/Docker容器生命周期管理.md Normal file
View File

@@ -0,0 +1,143 @@
---
title: "Docker容器生命周期管理"
type: concept
tags: [docker, container, lifecycle, operations]
date: 2026-04-22
---
# Docker容器生命周期管理
## Definition
Docker 容器生命周期管理是指对容器的创建、启动、停止、删除等各阶段进行规范操作的过程，是 Home Server 日常运维的基础技能。
## Lifecycle States
```
created → starting → running → stopping → stopped → removing → removed
↑ ↓
└────────── restarting ←──────┘
```
## Core Commands
### 查看
```bash
# 查看运行中的容器
docker ps
# 查看所有容器（包括已停止）
docker ps -a
# 查看特定应用的容器
docker ps -a | grep portainer
# 查看容器详细信息
docker inspect <container_name_or_id>
```
### 启动与停止
```bash
# 停止运行中的容器
docker stop <container_name_or_id>
# 强制停止（SIGKILL，8秒超时后强制终止）
docker kill <container_name_or_id>
# 启动已停止的容器
docker start <container_name_or_id>
# 重启容器（stop + start）
docker restart <container_name_or_id>
```
### 删除
```bash
# 删除已停止的容器
docker rm <container_name_or_id>
# 强制删除运行中的容器（先停止再删除）
docker rm -f <container_name_or_id>
# 删除所有已停止的容器
docker container prune
# 一条命令停止并删除
docker stop <container_name> && docker rm <container_name>
```
### 完整重建流程（以 Portainer 为例）
```bash
# 1. 停止容器
docker stop portainer
# 2. 删除容器
docker rm portainer
# 3. (可选) 删除数据卷
docker volume ls | grep portainer
docker volume rm portainer_data
# 4. (可选) 删除网络
docker network ls | grep portainer
docker network rm portainer_network
# 5. 重新部署
docker compose up -d
```
## Lifecycle Management Best Practices
### 1. Always Stop Before Remove
删除运行中的容器前应先停止，否则需要使用 `-f` 强制删除。强制删除可能导致数据丢失或不一致状态。
### 2. Check Dependencies
删除容器前检查是否有其他容器依赖它：
```bash
docker inspect <container> --format '{{.HostConfig.Links}}'
```
### 3. Use --filter for Bulk Operations
```bash
# 删除所有已停止的容器
docker container prune
# 删除所有 portainer 相关容器
docker rm $(docker ps -a --filter "name=portainer" -q)
# 删除所有退出的容器
docker rm $(docker ps -a --filter "status=exited" -q)
```
### 4. Label-based Lifecycle
给容器打标签以便批量管理：
```bash
# 创建时打标签
docker run --label "env=production" --label "app=web" nginx
# 按标签查找
docker ps --filter "label=env=production"
```
## Data Persistence
容器删除后，**绑定挂载**（bind mount）的数据仍然保留，但**匿名卷**（anonymous volume）可能丢失。使用命名卷（named volume）确保数据持久化：
```yaml
volumes:
- portainer_data:/data # 命名卷，删除容器后数据保留
# vs
volumes:
- /data # 匿名卷，不推荐
```
## Related Concepts
- [[Docker卷]] — 容器数据的持久化机制
- [[Docker Network]] — 容器的网络连接生命周期
- [[Docker Compose]] — 多容器应用的声明式生命周期管理
- [[Docker堆栈]] — 多容器协同工作栈的整体生命周期
## Related Entities
- [[Portainer]] — 需要生命周期管理的典型容器应用
- [[Docker]] — 生命周期管理的底层平台
## See Also
- [[如何删除旧的废弃的docker-container-volume]] — Portainer 重装的完整实操记录

185
wiki/concepts/Docker警告处理.md Normal file
View File

@@ -0,0 +1,185 @@
---
title: "Docker警告处理"
type: concept
tags: [docker, troubleshooting, warnings, compose]
date: 2026-04-22
---
# Docker警告处理
## Definition
Docker 在执行 `docker compose up` 或 `docker compose down` 时常会产生警告（WARNING），这些警告通常表示资源命名冲突或配置不一致。虽然不一定导致功能故障，但了解其根因有助于正确处理和预防。
## Common Warnings
### WARN 1: Network 已存在但不是当前项目创建
**典型警告信息**：
```
WARNING: Found orphan containers ([container_name]) for this project.
WARNING: Network portainer_network declared as external, but it does not exist
```
**根因分析**：
- 使用了不同的 compose 文件（或不同的项目目录名）部署过同名应用
- Docker Compose 以**项目目录名**作为网络/卷名前缀：`${PROJECT_NAME}_${network_name}`
- 之前的项目创建了 `portainer_network`，新 compose 声明了同名网络但找不到对应资源
**示例场景**：
```
# 目录 ~/portainer-deploy 运行过
docker compose up -d
# → 创建网络 portainer-deploy_portainer_network
# 目录 ~/my-portainer 运行新的 compose
docker compose up -d
# → 尝试创建 my-portainer_portainer_network
# → 与旧项目冲突
```
**解决方案**：
**方案 A：复用旧资源（数据保留）**
```yaml
networks:
portainer_network:
external: true
```
Compose 不会创建网络，直接使用已存在的 `portainer_network`。
**方案 B：删除旧资源（干净重建）**
```bash
# 1. 查看网络
docker network ls | grep portainer
# 2. 查看是否有容器正在使用
docker network inspect portainer_network --format '{{range .Containers}}{{.Name}} {{end}}'
# 3. 断开仍连接的网络（如果有）
docker network disconnect portainer_network <container>
# 4. 删除网络
docker network rm portainer_network
# 5. 重新 up
docker compose up -d
```
---
### WARN 2: Volume 已存在但属于另一个 Compose 项目
**典型警告信息**：
```
WARNING: Volume portainer_data exists but was not created for service 'portainer'.
It will not be used.
```
**根因分析**：
- 之前用不同的项目名部署过 Portainer，创建了旧卷（如 `portainer_portainer_data`）
- 新 compose 声明的卷名（如 `portainer_data`）是不同命名前缀下的卷
- Docker 认为旧卷不是为当前服务创建的，可能不兼容
**解决方案**：
**方案 A：复用旧卷（数据保留）**
```yaml
volumes:
portainer_data:
external: true
```
**方案 B：删除旧卷（数据丢失风险）**
```bash
# 1. 查看所有 portainer 相关卷
docker volume ls | grep portainer
# 2. 查看卷详细信息
docker volume inspect portainer_portainer_data
# 3. 删除旧卷（注意：会丢失数据）
docker volume rm portainer_portainer_data
# 4. 重新 up
docker compose up -d
```
**⚠️ 警告**：删除 Volume 会永久丢失数据。删除前确认是否需要保留数据。
---
### WARN 3: Found Orphan Containers
**典型警告信息**：
```
WARNING: Found orphan containers ([portainer]) for this project.
```
**根因**：compose 文件中删除了某个服务定义，但对应的容器仍存在于 Docker 中。
**解决方案**：
```bash
# 方案 A：删除孤儿容器
docker rm portainer
# 方案 B：撤销 compose 文件修改，恢复服务定义
```
---
## Prevention Best Practices
### 1. 使用固定的项目名
```bash
# 指定项目名，避免目录名作为前缀
docker compose -p my-app up -d
# 或在 .env 文件中固定
COMPOSE_PROJECT_NAME=my-app
```
### 2. 在部署前先清理
```bash
# 干净部署前先停止并删除
docker compose down
docker compose up -d
```
### 3. 统一使用 external: true
对于已存在资源的场景，统一在 compose 中声明 `external: true`：
```yaml
volumes:
portainer_data:
external: true
networks:
portainer_network:
external: true
```
### 4. 使用一致的目录名
避免频繁变更 compose 文件所在目录，防止命名前缀混乱。
## Troubleshooting Flowchart
```
出现 WARN 警告
↓
识别警告类型（Network / Volume / Container）
↓
确认是否需要保留旧资源的数据
↓
├─ 需要保留 → 改用 external: true
└─ 不需要保留 → 删除旧资源后重新 up
```
## Related Concepts
- [[Docker Compose]] — compose 文件中的 external 声明
- [[Docker卷]] — Volume 的生命周期
- [[Docker Network]] — Network 的生命周期
- [[Docker容器生命周期管理]] — 容器的 CRUD 操作
## Related Entities
- [[Portainer]] — 常见产生警告的容器应用
## See Also
- [[如何删除旧的废弃的docker-container-volume]] — 完整实操记录

77
wiki/concepts/HTTPS自动化证书.md Normal file
View File

@@ -0,0 +1,77 @@
# HTTPS自动化证书
> HTTPS自动化证书，Caddy 自动申请和管理 Let's Encrypt SSL 证书的机制，无需手动配置证书续期和文件路径。
## Overview
Caddy 是用 Go 语言编写的现代化 Web 服务器，其核心特性之一是**自动 HTTPS**——自动为配置中的域名申请 Let's Encrypt 免费证书，并在到期前自动续期。本方案中 Caddy 运行在 RackNerd VPS 上，为 *.ishenwei.online 的所有子域名提供统一的 HTTPS 访问。
## How It Works
### 申请流程
1. Caddy 监听 80 端口（HTTP）和 443 端口（HTTPS）
2. 收到域名请求后，自动向 Let's Encrypt 的 ACME 服务器发起证书申请
3. Let's Encrypt 通过 HTTP-01 或 TLS-ALPN-01 挑战验证域名所有权
4. 验证通过后，证书下载并存储在 Caddy 本地（`~/.caddy`）
5. 证书到期前自动续期（默认提前30天）
### Caddyfile 配置示例
```
*.ishenwei.online {
tls {
dns cloudflare {env.CF_API_TOKEN}
}
reverse_proxy /* localhost:8080
}
```
## vs 传统 Nginx/Apache 方案
|| 特性 | Caddy | Nginx/Apache + Certbot |
|------|------|------|------------------------|
| 证书申请 | 自动 | 需手动 certbot |
| 证书续期 | 自动 | 需配置 cron + certbot renew |
| 证书路径 | 自动管理 | 需手动指定 |
| 配置文件 | 简洁 | 复杂 |
| 性能 | 轻量 | 成熟 |
## Architecture Context
本方案中 Caddy 接收来自公网的 HTTPS 请求后，根据域名将流量反向代理到对应的 FRP remotePort：
```
[公网请求]
https://grafana.ishenwei.online
│
▼
[RackNerd VPS: Caddy]
① 验证证书（自动）
② TLS 解密
③ 反向代理到 localhost:13000
│
▼
[FRP Server]
隧道传输到内网节点
│
▼
[Ubuntu Server 1: Grafana]
端口 3000
```
## Key Advantages
1. **零配置证书**：无需手动管理证书文件和续期脚本
2. **自动 HTTP→HTTPS 重定向**：Caddy 默认将所有 HTTP 请求升级到 HTTPS
3. **Wildcard 证书**：通过 DNS-01 挑战支持 `*.ishenwei.online` 泛域名证书
4. **现代协议支持**：默认启用 HTTP/2 和 TLS 1.3
## Related Concepts
- [[反向代理]] — Caddy 的核心功能
- [[DNS托管]] — Cloudflare DNS 验证泛域名所有权
- [[内网穿透]] — FRP 隧道传输机制
- [[TLS 1.3]] — 最新 TLS 协议版本
- [[ACME]] — Let's Encrypt 证书自动颁发协议
## Related Entities
- [[Caddy]] — 自动 HTTPS 实现者
- [[RackNerd]] — Caddy 运行环境
- [[Cloudflare]] — DNS 服务提供商，支持 DNS-01 挑战
- [[FRP]] — 内网服务的传输通道

63
wiki/concepts/Headless-服务器.md Normal file
View File

@@ -0,0 +1,63 @@
---
title: "Headless 服务器"
type: concept
tags: [服务器, 无头运行, 远程管理]
---
# Headless 服务器
> Headless 服务器（无头服务器）指不连接本地显示器、键盘、鼠标等外设的服务器，通过网络远程管理和访问。
## 概述
Headless 服务器是 Home Server、家庭实验室和数据中心常见的部署模式。Mac Mini 作为 Home Server 时，即以 Headless 模式运行，依赖 RustDesk/VNC 等远程桌面工具进行交互管理。
## 核心挑战
| 挑战 | macOS 解决方案 | Linux 解决方案 |
|------|---------------|---------------|
| 自动睡眠导致连接中断 | `pmset -a sleep 0` | systemd-logind HandleLidSwitch |
| 无显示器导致锁屏 | `pmset -a displaysleep 0` | 无直接对应 |
| 深度休眠导致无法远程唤醒 | `pmset -a standby 0 hibernatemode 0` | systemctl mask sleep.target |
| 需要远程管理能力 | RustDesk/VNC | SSH/RDP |
## macOS Headless 最佳实践
```bash
# 防止所有睡眠（核心配置）
sudo pmset -a sleep 0 displaysleep 0 standby 0 hibernatemode 0
# 启用网络唤醒
sudo pmset -a womp 1
# 临时保持唤醒
caffeinate -d -i -s
```
## Linux Headless（Ubuntu Server）
- [[HandleLidSwitch]] = ignore：合盖继续运行
- [[systemd-logind]]：电源管理核心组件
- SSH：远程管理的事实标准
## 与传统服务器的对比
| 特性 | 数据中心服务器 | Headless 服务器 |
|------|-------------|---------------|
| 显示器 | 通常有 KVM 切换器 | 无 |
| 物理访问 | 通常托管机房 | Home Office |
| 电源管理 | BMC/IPMI 远程管理 | 操作系统级别配置 |
| 睡眠处理 | 通常禁用 | 必须明确禁用 |
## 相关概念
- [[pmset]] — macOS Headless 电源配置工具
- [[caffeinate]] — macOS 临时防止睡眠
- [[Wake-on-LAN]] — Headless 远程唤醒
- [[HandleLidSwitch]] — Linux Headless 合盖配置
- [[系统睡眠管理]] — 操作系统睡眠机制
## 相关实体
- [[Mac Mini M4]] — 典型的 Home Headless 服务器
- [[Ubuntu Server]] — 另一常见的 Headless 服务器操作系统

1
wiki/concepts/NFS网络备份.md
View File

@@ -44,3 +44,4 @@ NFS（Network File System）网络备份是指通过 NFS 协议将备份数据
- [[clonezilla对ubuntu-server进行全盘镜像备份]]
- [[ubuntu服务器通过rsync实现日常增量备份]]
- [[如何在ubuntu-server上通过nfs挂载synology-nas上的共享文件夹]]
- [[rsync]] — Entity 页面

96
wiki/concepts/S3-兼容对象存储.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: S3-兼容对象存储
type: concept
tags: [storage, s3, minio]
date: 2025-12-29
---
# S3-兼容对象存储
## Definition
S3-兼容对象存储是指实现了 Amazon S3 API 的对象存储系统，可以在不修改代码的情况下替换 AWS S3 使用。包括 MinIO、Cloudflare R2、Backblaze B2、SeaweedFS 等。
## Core S3 Concepts
| 概念 | 说明 |
|------|------|
| Bucket | 存储桶，类似顶级文件夹 |
| Object | 对象，文件及其元数据 |
| Key | 对象的唯一标识符（路径） |
| Region | 区域，物理位置 |
| ACL | 访问控制列表 |
| Policy | IAM 策略 |
| Presigned URL | 预签名 URL，限时访问 |
## S3 vs Traditional Storage
| 特性 | S3 对象存储 | 传统文件系统 |
|------|-------------|--------------|
| 访问方式 | HTTP API | 文件路径 |
| 扩展性 | 无限扩展 | 受限于单盘/RAID |
| 成本 | 按量计费 | 一次性硬件 |
| 元数据 | 键值对灵活扩展 | 固定属性 |
| 原子性 | 最终一致性 | 强一致性 |
| 版本控制 | 原生支持 | 需额外配置 |
## MinIO Configuration for Zipline
```yaml
environment:
STORAGE_ENGINE: s3
S3_BUCKET: zipline-bucket
S3_ENDPOINT: http://minio:9000
S3_ACCESS_KEY: admin
S3_SECRET_KEY: Abcd_1234
S3_REGION: us-east-1
S3_FORCE_PATH_STYLE: "true" # 重要：MinIO 需要此设置
```
关键参数 `S3_FORCE_PATH_STYLE: "true"`：
- MinIO 默认使用虚拟主机风格（bucket.minio:9000）
- 部分应用需要路径风格（minio:9000/bucket）
- 设置为 true 确保兼容性
## Anonymous Access with mc
```bash
# 设置别名
mc alias set local http://192.168.3.17:9000 admin password
# 创建 bucket
mc mb local/zipline-bucket
# 设置匿名访问权限
mc anonymous set public local/zipline-bucket # 公共读写
mc anonymous set download local/zipline-bucket # 仅下载
# 查看匿名策略
mc anonymous list local/zipline-bucket
```
## Cloud Provider Comparison
| 提供商 | S3 兼容 | 出口流量计费 | 最小存储量 | 特色 |
|--------|----------|--------------|------------|------|
| AWS S3 | 原生 | $0.09/GB | 无 | 功能最全 |
| Cloudflare R2 | 是 | **免费** | 无 | 无出口费 |
| Backblaze B2 | 是 | $0.01/GB | 无 | 性价比高 |
| MinIO | 是 | 0 | 无 | 自托管 |
| SeaweedFS | 是 | 0 | 无 | 大文件优化 |
## Use Cases
1. **备份存储**：低频访问但需高持久性
2. **静态资源**：CDN 回源存储
3. **图床/媒体库**：直接 URL 访问
4. **AI 模型权重**：大文件存储
## Connections
- [[MinIO]] ← implements ← [[S3-兼容对象存储]]
- [[Zipline]] ← uses ← [[S3-兼容对象存储]]
- [[图床]] ← backed by ← [[S3-兼容对象存储]]
## Related Concepts
- [[对象存储]]
- [[图床]]
- [[数据一致性]]

74
wiki/concepts/SOCKS5代理.md Normal file
View File

@@ -0,0 +1,74 @@
# SOCKS5代理
> SOCKS5，本地科学上网代理协议，监听 127.0.0.1:10808，在 Mac Mini、Ubuntu1、Ubuntu2 上正常运行，NAS 上仅本机监听。
## Overview
SOCKS5 代理是一种网络协议，通过 SOCKS 代理服务器转发客户端的网络请求，支持 TCP 和 UDP。本方案中各节点通过 v2rayA 或类似代理客户端在本地启动 SOCKS5 代理服务，供本机应用走科学上网通道。
## Node Status
|| 节点 | IP | 端口 | 状态 | FRP 暴露 |
|------|-----|-----|------|----------|
| Mac Mini M4 | 127.0.0.1 | 10808 | ✅ 正常 | — |
| Ubuntu Server 1 | 127.0.0.1 | 10808 | ✅ 正常 | — |
| Ubuntu Server 2 | 127.0.0.1 | 10808 | ✅ 正常 | — |
| Synology NAS | 127.0.0.1 | 20170 | ❌ 仅本机监听 | 否 |
## Usage Patterns
### 终端命令级（ProxyChains）
ProxyChains 通过 LD_PRELOAD 劫持 socket 调用，强制任意终端命令走 SOCKS5 代理：
```bash
# /etc/proxychains4.conf
socks5 127.0.0.1 10808
# 使用
proxychains4 curl https://google.com
```
### Git 全局代理
Git 不读取系统环境变量，必须显式配置：
```bash
git config --global http.proxy socks5://127.0.0.1:10808
git config --global https.proxy socks5://127.0.0.1:10808
```
### Docker Daemon 代理
通过 systemd drop-in 文件注入环境变量：
```bash
# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=socks5://127.0.0.1:10808"
Environment="HTTPS_PROXY=socks5://127.0.0.1:10808"
```
### Docker 容器环境变量
```bash
# 容器内使用 ALL_PROXY 环境变量
docker run -e ALL_PROXY=socks5://172.24.0.1:10808 ...
```
## Key Distinction: socks5 vs socks5h
- **socks5**：DNS 解析在本地完成，可能 DNS 污染
- **socks5h**：DNS 解析由代理服务器完成，防止本地 DNS 污染
```bash
curl -x socks5h://127.0.0.1:10808 https://google.com
```
## Docker 网络网关 IP
Docker 容器内访问宿主机的 IP 不是 127.0.0.1（那是容器自身），而是 Docker 网络网关 IP：
- bridge 网络默认：`172.17.0.1`
- 自定义网络（如 compose 项目）：`172.24.0.1`
## Related Concepts
- [[透明代理]] — V2RayA 通过 iptables 劫持系统出站流量
- [[环境变量代理]] — HTTP_PROXY/HTTPS_PROXY/ALL_PROXY 环境变量
- [[Docker Daemon 代理]] — systemd drop-in 方式为 docker pull 配置代理
- [[ProxyChains]] — 终端命令级流量劫持工具
- [[Git 全局代理]] — Git 专用代理配置
## Related Entities
- [[v2rayA]] — NAS 上的 SOCKS5 代理来源（端口20170）
- [[Mac Mini M4]] — SOCKS5 代理节点之一
- [[Ubuntu Server]] — SOCKS5 代理节点
- [[Synology NAS DS718]] — v2rayA 部署位置（仅本机监听）

66
wiki/concepts/Wake-on-LAN.md Normal file
View File

@@ -0,0 +1,66 @@
---
title: "Wake-on-LAN"
type: concept
tags: [网络, 远程管理, 电源管理]
---
# Wake-on-LAN
> Wake-on-LAN（WoL/WOL）是一种网络标准，允许管理员通过发送特定格式的"魔法包"（Magic Packet）远程唤醒处于关机或深度睡眠状态的计算机。
## 概述
Wake-on-LAN 通过网卡在系统关闭或深度睡眠时仍保持最低功耗监听，接收特定格式的广播包后触发开机。在 Home Server 场景中，配合 `pmset -a womp 1` 启用后，Mac Mini 关机后仍可通过网络被远程唤醒。
## 工作原理
1. **待机状态**：网卡在系统关机后仍保持低功耗，监听网络
2. **Magic Packet**：发送包含目标 MAC 地址的 UDP 数据包（端口 9）
3. **触发开机**：网卡收到 Magic Packet 后通过主板信号触发开机
## macOS 配置
```bash
# 启用 Wake-on-LAN
sudo pmset -a womp 1
# 验证状态
pmset -g | grep womp
```
## Linux 配置（ethtool）
```bash
# 查看网卡是否支持 WoL
ethtool eth0
# 启用 WoL（需 sudo）
ethtool -s eth0 wol g
# 持久化配置（写入 systemd 或 udev 规则）
```
## Home Server 场景
| 场景 | 说明 |
|------|------|
| [[Mac Mini M4]] | `pmset -a womp 1` 启用，通过 Magic Packet 从关机状态唤醒 |
| Ubuntu Server | `ethtool` 配置，配合 systemd 网络服务实现持久化 |
## Magic Packet 格式
Magic Packet 是 UDP 数据包（通常端口 7 或 9），包含：
- 6 字节的 `0xFF`
- 随后 16 次重复目标 MAC 地址
发送工具：`wakeonlan`（Linux/macOS）、`wol.exe`（Windows）、路由器管理界面
## 相关概念
- [[pmset]] — macOS WoL 启用方式
- [[系统睡眠管理]] — 睡眠模式与 WoL 的兼容性
- [[Headless 服务器]] — WoL 的典型应用场景
## 相关实体
- [[Mac Mini M4]] — WoL 的 macOS 配置对象

61
wiki/concepts/caffeinate.md Normal file
View File

@@ -0,0 +1,61 @@
---
title: "caffeinate"
type: concept
tags: [macOS, 电源管理, 临时防止睡眠]
---
# caffeinate
> macOS 临时防止系统睡眠的工具，不修改系统持久设置，按 Ctrl+C 停止。
## 概述
`caffeinate` 是 macOS 内置命令，用于在当前会话中临时防止系统进入睡眠状态。与 `pmset` 的永久配置不同，`caffeinate` 是即时生效、即时失效的临时方案，适合需要短期保持唤醒但不想修改系统设置的场景。
## 核心参数
| 参数 | 作用 |
|------|------|
| `-d` | 防止显示器睡眠 |
| `-i` | 防止系统空闲时睡眠 |
| `-s` | 防止系统睡眠（防止 AC Power 断开时进入睡眠） |
| `-u` | 模拟用户活动（防止睡眠） |
| `-t <secs>` | 指定超时秒数后允许睡眠 |
## 常用命令
```bash
# 防止显示器和系统睡眠（常用组合）
caffeinate -d -i -s
# 按 Ctrl+C 停止
```
## 使用场景
1. **临时测试**：验证某操作是否需要系统保持唤醒
2. **一次性任务**：执行大文件传输、备份等不希望被睡眠中断的任务
3. **替代 pmset**：不修改系统电源设置，仅在需要时保持唤醒
4. **与 pmset 对比**：pmset 永久配置 vs caffeinate 临时生效
## 与 pmset 的关系
- **pmset**：永久修改系统电源设置，重启后保留
- **caffeinate**：临时阻止睡眠，不修改系统设置，退出后恢复原状态
- 两者可互补使用：先用 pmset 配置合理的系统默认行为，再用 caffeinate 处理临时需求
## Home Server 场景
在 Mac Mini 作为 Home Server 时，`caffeinate` 通常不是首选方案，因为服务器需要长期持续运行，`pmset` 的永久配置更适合。但 `caffeinate` 可用于：
- 调试电源管理配置
- 临时升级/维护期间的保持唤醒
## 相关概念
- [[pmset]] — macOS 电源管理永久配置工具
- [[系统睡眠管理]] — 操作系统电源管理的通用框架
- [[Headless 服务器]] — caffeinate 的目标运行环境
## 相关实体
- [[Mac Mini M4]] — caffeinate 的典型应用平台

154
wiki/concepts/external配置.md Normal file
View File

@@ -0,0 +1,154 @@
---
title: "external配置"
type: concept
tags: [docker, compose, configuration, volume, network]
date: 2026-04-22
---
# external配置
## Definition
`external: true` 是 Docker Compose 文件中的一种声明式配置，用于告诉 Compose 某个 Volume 或 Network 已经存在，不要尝试创建它，而是直接使用已存在的资源。适用于需要保留数据、不希望 Compose 管理资源生命周期的场景。
## Syntax
### Volume（卷）
```yaml
volumes:
portainer_data:
external: true
# 引用时直接使用名称
services:
portainer:
volumes:
- portainer_data:/data
```
### Network（网络）
```yaml
networks:
portainer_network:
external: true
services:
portainer:
networks:
- portainer_network
```
## Behavior Comparison
| 配置 | Compose up | Compose down |
|------|-----------|-------------|
| `external: false`（默认） | 自动创建资源 | 自动删除资源 |
| `external: true` | **不会创建**，直接使用已存在的 | **不会删除**，保持资源 |
| `external: { name: xxx }` | 使用指定名称的已存在资源 | 不会删除 |
## Common Use Cases
### Case 1: 保留数据重装应用
```yaml
# Portainer 重装时保留 portainer_data 卷
volumes:
portainer_data:
external: true
services:
portainer:
image: portainer/portainer-ce:lts
volumes:
- portainer_data:/data
```
这样即使删除并重建 Portainer 容器，用户账户和配置也不会丢失。
### Case 2: 多个 Compose 共享网络
```yaml
# compose-a.yml
networks:
shared_backend:
external: true
# compose-b.yml（同一机器上的另一个项目）
networks:
shared_backend:
external: true
```
两个 compose 文件可以连接同一个外部网络，实现跨项目通信。
### Case 3: 预创建的基础设施
运维人员预先创建好 Volume/Network，开发者通过 `external: true` 引用：
```bash
# 运维预先创建
docker network create monitoring
docker volume create prometheus_data
# 开发 compose 中声明
networks:
monitoring:
external: true
volumes:
prometheus_data:
external: true
```
## Limitations
### 1. 资源不存在会导致错误
```bash
# 如果 portainer_data 卷不存在，compose up 会报错：
# ERROR: Volume portainer_data declared as external, but could not be found
```
**解决**：先确认资源存在，或使用脚本预创建：
```bash
docker volume create portainer_data 2>/dev/null || true
docker compose up -d
```
### 2. 不能控制生命周期
`external: true` 资源不会被 `docker compose down --volumes` 删除。需要手动清理：
```bash
docker volume rm portainer_data
docker network rm portainer_network
```
### 3. Compose 文件中的其他字段无效
```yaml
volumes:
portainer_data:
external: true
driver: local # ❌ 会被忽略
driver_opts: {} # ❌ 会被忽略
```
## External with Custom Name
如果已存在的资源名称与 compose 中声明的名称不同，使用 `external.name` 指定：
```yaml
volumes:
app_data:
external:
name: old_project_data_volume
```
## Best Practices
1. **始终显式声明**：所有 `external` 资源都应在 compose 文件中明确声明，便于维护者理解
2. **文档化**：在 README 中记录哪些资源需要预先创建
3. **命名规范**：使用统一的前缀或命名约定（如 `project_name_resource`）
4. **验证脚本**：部署前运行验证脚本确保依赖资源存在
## Related Concepts
- [[Docker Compose]] — external 配置所在的上下文
- [[Docker卷]] — external volume 的目标对象
- [[Docker Network]] — external network 的目标对象
- [[Docker容器生命周期管理]] — external 资源与生命周期管理的关系
- [[Docker警告处理]] — external 配置用于解决警告的典型场景
## Related Entities
- [[Portainer]] — 典型的需要 external 配置保留数据的应用
## See Also
- [[如何删除旧的废弃的docker-container-volume]] — external 配置的实操案例
- [[Docker堆栈]] — 多容器场景下的 external 资源管理

72
wiki/concepts/passkey.md Normal file
View File

@@ -0,0 +1,72 @@
# Passkey
## Aliases
- Passkey
- WebAuthn
- FIDO2
- 无密码认证
- FIDO2/WebAuthn 凭证
## Type
Concept / Authentication Standard
## Description
Passkey 是一种基于 FIDO2/WebAuthn 标准的无密码认证方案，使用公钥加密替代传统密码，提供更高的安全性和用户体验。
## How It Works
### Registration
```
1. 用户在网站上选择"创建 Passkey"
2. 网站生成挑战（challenge）并发送给浏览器
3. 用户通过设备验证（指纹、Face ID、PIN等）
4. 设备生成公钥/私钥对，私钥保存在设备安全区域
5. 公钥发送给服务器存储
```
### Authentication
```
1. 用户选择使用 Passkey 登录
2. 服务器发送挑战（challenge）
3. 用户通过设备验证（指纹、Face ID、PIN等）
4. 设备使用私钥对挑战签名
5. 服务器用公钥验证签名，完成认证
```
## Key Characteristics
| 特性 | 说明 |
|------|------|
| 无密码 | 不需要记忆密码 |
| 防钓鱼 | 绑定特定域名，无法用于钓鱼网站 |
| 防重放 | 每次使用不同的挑战，无法重放攻击 |
| 跨设备 | 可以同步到云端（iCloud Keychain、Google Password Manager） |
| 标准 | FIDO2 / W3C WebAuthn |
## Passkey vs Traditional 2FA
| 对比项 | Passkey | TOTP |
|--------|---------|------|
| 用户体验 | 更便捷（生物识别） | 需要手动输入6位码 |
| 安全性 | 更高（公钥加密） | 中等（共享密钥） |
| 离线支持 | 依赖设备 | 支持 |
| 跨设备同步 | 依赖平台生态 | 通过 Secret 迁移 |
| 普及度 | 正在增长 | 广泛使用 |
## Passkey Support in Password Managers
### Bitwarden (Official)
- Passkey 功能需要**付费会员**
### NodeWarden
- 原生支持 Passkey，**免费**提供
- 完全兼容 Bitwarden 官方客户端
## Related Concepts
- [[Multi-factor-Authentication]] — Passkey 可作为 MFA 的第一因素
- [[TOTP]] — 传统双因素认证方案
- [[Self-Hosted Password Manager]] — 自托管密码管理器需要支持 Passkey
## Source
- [[nodewarden-把-bitwarden-搬上-cloudflare-workers-彻底告别服务器]]

74
wiki/concepts/pmset.md Normal file
View File

@@ -0,0 +1,74 @@
---
title: "pmset"
type: concept
tags: [macOS, 电源管理, 系统管理]
---
# pmset
> macOS 系统电源管理命令行工具，用于查询和修改 macOS 的电源设置（sleep/displaysleep/standby/hibernatemode/womp）。
## 概述
`pmset` 是 macOS 内置的电源管理工具，可查看和配置系统睡眠、显示器睡眠、待机、休眠等行为。在 Mac Mini 作为 Home Server（无显示器）运行时，正确的 `pmset` 配置是确保 7×24 持续可访问的关键。
## 核心参数
### 查询命令
| 命令 | 作用 |
|------|------|
| `pmset -g` | 显示当前所有电源设置 |
| `pmset -g sleep` | 显示睡眠相关设置 |
| `pmset -g displaysleep` | 显示显示器睡眠设置 |
### 设置命令（永久生效）
| 命令 | 作用 |
|------|------|
| `pmset -a sleep 0` | 禁止系统睡眠 |
| `pmset -a displaysleep 0` | 禁止显示器关闭 |
| `pmset -a standby 0` | 禁止待机模式 |
| `pmset -a hibernatemode 0` | 禁止休眠（内存保存到磁盘） |
| `pmset -a womp 1` | 启用网络唤醒（WOL） |
### 参数作用域
| 参数 | 含义 |
|------|------|
| `-a` | 应用于所有电源模式（电池 + 电源适配器） |
| `-b` | 仅电池模式 |
| `-c` | 仅电源适配器模式 |
## Home Server 最佳实践
将以下命令写入启动脚本或通过 MDM 配置：
```bash
sudo pmset -a sleep 0
sudo pmset -a displaysleep 0
sudo pmset -a standby 0
sudo pmset -a hibernatemode 0
sudo pmset -a womp 1
```
## 与 Linux 对应关系
| macOS (pmset) | Linux (systemd-logind) |
|---|---|
| `sleep 0` | `HandleLidSwitch=ignore` |
| `displaysleep 0` | 无直接对应（Linux 无显示器概念） |
| `standby 0` | `AllowSuspend=no` |
| `hibernatemode 0` | `HibernateMode=off` |
| `womp 1` | 无直接对应（需 ethtool 配置 WoL） |
## 相关概念
- [[caffeinate]] — 临时防止睡眠的工具，不修改系统设置
- [[Wake-on-LAN]] — 网络唤醒，与 `womp` 参数相关
- [[系统睡眠管理]] — 操作系统电源管理的通用概念
- [[Headless 服务器]] — 无显示器的服务器，pmset 配置的目标场景
## 相关实体
- [[Mac Mini M4]] — pmset 的典型应用平台

74
wiki/concepts/proxychains.md Normal file
View File

@@ -0,0 +1,74 @@
# ProxyChains
## Aliases
- proxychains
- proxychains4
- proxychains-ng
## Definition
ProxyChains 是一个基于 LD_PRELOAD 机制的终端代理劫持工具，通过预先加载（preload）一个共享库来拦截动态链接程序（如 curl、wget、git）的 socket 系统调用，将网络流量重定向到配置的代理服务器。
## Type
[[概念]]
## Core Mechanism
### LD_PRELOAD 劫持原理
ProxyChains 在运行时通过 `LD_PRELOAD` 环境变量将自己编译的共享库（`libproxychains4.so`）注入到目标程序的进程空间。当目标程序调用 `connect()` 等 socket 函数时，实际调用的是 ProxyChains 提供的包装函数，该函数将连接重定向到配置文件中指定的代理服务器。
### 优势
- **无需源码修改**：任何使用动态链接库的程序均可通过前置 proxychains4 执行而自动走代理
- **透明性**：目标程序无需感知代理的存在
- **灵活性**：支持 socks4 / socks5 / http 多种代理类型
## Configuration
### ProxyChains 配置文件
```bash
sudo nano /etc/proxychains4.conf
```
### ProxyList 配置格式
```ini
[ProxyList]
# 格式: 类型 IP 端口
socks5 127.0.0.1 10808
```
### 使用方式
```bash
# 任何命令前加 proxychains4 前缀即可走代理
proxychains4 curl https://www.google.com
proxychains4 wget https://github.com/example/repo
proxychains4 git clone https://github.com/...
proxychains4 apt-get update
```
## Limitations
- **仅支持动态链接程序**：静态编译的程序（如 alpine 容器中的命令）无法被劫持
- **不支持 UDP**：ProxyChains 4.x 主要处理 TCP 连接
- **不支持链式代理**（新版可配置但复杂）：建议直接使用单一代理
- **不支持 ICMP**：ping 命令无法通过 ProxyChains 走代理
- **DNS 行为**：取决于配置中的 `proxy_dns` 设置，socks5h 模式下 DNS 由代理服务器解析
## Related Concepts
- [[SOCKS5 协议]]：ProxyChains 最常使用的代理协议
- [[SOCKS5h 代理]]：DNS 由代理服务器解析的 SOCKS5 变体，推荐配合 ProxyChains 使用
- [[LD_PRELOAD]]：Linux 动态链接库预加载机制，ProxyChains 的底层技术基础
- [[环境变量代理]]：另一种让程序走代理的方式（HTTP_PROXY/HTTPS_PROXY），与 ProxyChains 互补
- [[Git 全局代理]]：Git 不读取环境变量代理，需要通过 `git config` 显式配置
## Related Entities
- [[v2rayN]]：ProxyChains 常见的代理来源（提供 10808 SOCKS5 端口）
- [[代理协议]]：ProxyChains 支持 socks4 / socks5 / http 代理协议
## Related Sources
- [[ubuntu-server科学上网]]：ProxyChains 的完整配置流程
## Summary
ProxyChains 是 Ubuntu Server 终端场景下"让任意命令走代理"的最灵活方案，通过 LD_PRELOAD 劫持 socket 调用，无需目标程序支持代理。相比 Git 全局代理配置和 Docker Daemon 代理配置，ProxyChains 适用范围最广，但仅限于动态链接程序和 TCP 连接。

85
wiki/concepts/self-hosted-password-manager.md Normal file
View File

@@ -0,0 +1,85 @@
# Self-Hosted Password Manager
## Aliases
- Self-Hosted Password Manager
- 自托管密码管理器
- 私有密码管理器
- 自建密码服务
## Type
Concept / Architecture Pattern
## Description
自托管密码管理器是指用户在自己的基础设施上部署和运行密码管理服务，而非使用第三方云服务，所有数据存储在用户可控的服务器或平台中。
## Deployment Architectures
### Traditional Self-Hosting
```
用户设备 → 自托管服务器 (VPS/Dedicated) → 数据库
```
- 需要维护服务器（OS 更新、安全补丁）
- 需要管理数据库备份
- 示例：Bitwarden 自托管、Vaultwarden
### Serverless Self-Hosting
```
用户设备 → 云函数/边缘计算 (Cloudflare Workers) → 云数据库 (D1/R2)
```
- 无需维护服务器
- 平台负责底层运维
- 示例：NodeWarden
### Local-Only
```
用户设备 → 本地数据库
```
- 完全离线，不同步
- 示例：KeePass
## Comparison Matrix
| 方案 | 服务器 | 数据控制 | 维护成本 | 跨设备同步 | 成本 |
|------|--------|----------|----------|------------|------|
| 官方云服务 | 厂商 | 厂商 | 无 | ✅ | 订阅制 |
| Bitwarden 自托管 | 用户 | 用户 | 高 | ✅ | 服务器成本 |
| NodeWarden | 无 | 用户 | 低 | ✅ | 接近免费 |
| KeePass | 无 | 用户 | 无 | 手动 | 免费 |
## Key Considerations
### Security
- 数据加密（服务端加密、传输加密）
- 访问控制（强密码、2FA）
- 审计日志
### Privacy
- 数据主权（谁控制服务器）
- 合规要求（GDPR、HIPAA 等）
- 数据存储位置
### Reliability
- 备份策略
- 灾难恢复
- 可用性 SLA
### Cost
- 服务器/云资源成本
- 域名费用
- 维护人力成本
## Related Concepts
- [[TOTP]] — 双因素认证，通常与密码管理器配合使用
- [[Passkey]] — 新一代无密码认证标准
- [[Serverless Computing]] — NodeWarden 使用的架构范式
- [[Edge Computing]] — 边缘计算平台（Cloudflare Workers）
## Popular Self-Hosted Options
- [[Bitwarden]] — 官方自托管服务器（Docker）
- [[NodeWarden]] — Cloudflare Workers 版本（[[Cloudflare Workers]]）
- [[Vaultwarden]] — Bitwarden API 兼容实现，轻量级 Rust 版本
## Source
- [[nodewarden-把-bitwarden-搬上-cloudflare-workers-彻底告别服务器]]

62
wiki/concepts/totp.md Normal file
View File

@@ -0,0 +1,62 @@
# TOTP (Time-based One-Time Password)
## Aliases
- TOTP
- Time-based One-Time Password
- 动态口令
- 一次性密码
## Type
Concept / Security Protocol
## Description
TOTP 是一种基于时间的一次性密码算法，通过共享密钥和当前时间戳生成动态验证码，广泛用于双因素认证（2FA）。
## How It Works
```
1. 服务端与客户端共享一个 Secret Key（密钥）
2. 双方使用相同的算法：
TOTP = HMAC-SHA1(Secret Key, floor(Unix_Time / 30))
3. 每 30 秒生成一个新的 6 位数字验证码
4. 用户在登录时输入该验证码完成身份验证
```
## Key Characteristics
| 特性 | 说明 |
|------|------|
| 时效性 | 每 30 秒更新一次 |
| 长度 | 通常 6 位数字 |
| 离线可用 | 不需要网络连接（和时间同步） |
| 算法标准 | RFC 6238 |
| 变体 | HOTP（基于计数器）、TOTP（基于时间） |
## TOTP in Password Managers
### Bitwarden (Official)
- TOTP 功能需要**付费会员**
- 自动填充验证码
- 支持大多数网站的双因素认证
### NodeWarden
- 通过 `TOTP_SECRET` 环境变量**免费**提供
- 配置后可在 Bitwarden 客户端自动获取验证码
## Setting Up TOTP Secret
在 NodeWarden 中设置 TOTP：
1. 在 Two-Factor Auth 页面获取 TOTP Secret（Base32 编码字符串）
2. 将 Secret 填入 `TOTP_SECRET` 环境变量
3. 在 Bitwarden 客户端添加 TOTP：大多数网站在设置 2FA 时会显示密钥
4. 在 Bitwarden 客户端设置 → 高级 → 身份验证器 TOTP 中填入密钥
## Related Concepts
- [[Multi-factor-Authentication]] — TOTP 是 MFA 的一种因素
- [[Passkey]] — 基于 WebAuthn 的无密码认证，比 TOTP 更安全
- [[Self-Hosted Password Manager]] — 自托管密码管理器通常内置 TOTP 支持
## Source
- [[nodewarden-把-bitwarden-搬上-cloudflare-workers-彻底告别服务器]]

75
wiki/concepts/图床.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: 图床
type: concept
tags: [image, hosting, web]
date: 2025-12-29
---
# 图床
## Definition
图床（Image Hosting）是指托管图片/媒体文件的服务，通过 URL 直接访问托管的文件。传统图床（如 Imgur、SM.MS）是第三方云服务；自托管图床则在自有服务器上运行，提供完全的数据控制。
## Alternatives Comparison
| 图床方案 | 存储位置 | 成本 | 控制权 | 适用场景 |
|----------|----------|------|--------|----------|
| Imgur | 云端 | 免费有限 | 无 | 临时分享 |
| SM.MS | 云端 | 免费 | 无 | 临时分享 |
| Cloudflare R2 | 云端（S3兼容） | 按量计费 | 部分 | 生产环境 |
| **MinIO + Zipline** | 本地 NAS | 仅电费 | 完全 | 自托管 |
| Chevereto | 自托管 | 仅服务器 | 完全 | 自托管 |
## Architecture Patterns
### Pattern 1: MinIO + Zipline（本方案）
```
[Zipline UI/API] → [S3 API] → [MinIO] → [NAS Storage]
↑
[PostgreSQL]
(metadata)
```
### Pattern 2: Direct Upload to S3
```
[Client] → [Presigned URL] → [AWS S3/R2/MinIO]
```
### Pattern 3: Traditional Self-Hosted
```
[Nginx] → [Local Filesystem] → [Disk/NAS]
```
## Key Design Considerations
1. **存储后端选择**
- S3 兼容（如 MinIO）：可迁移性强，与云端互通
- 本地文件系统：简单但迁移困难
2. **访问控制**
- Public Bucket：图片直接访问，无需认证
- Presigned URL：限时访问，适合私有内容
3. **元数据管理**
- 数据库存储：支持搜索、统计、管理
- 文件系统存储：简单但功能有限
4. **工作流集成**
- API 上传：[[n8n]]、脚本自动化
- 前端直传：用户体验好但需 CORS 配置
## MinIO + Zipline Specifics
- **MinIO**：S3 兼容对象存储，存储文件实体
- **Zipline**：图床应用层，提供 UI + API
- **PostgreSQL**：元数据存储（文件名、URL、时间戳等）
## Connections
- [[Zipline]] ← provides ← [[图床]]
- [[MinIO]] ← stores ← [[图床]] files
- [[n8n]] ← integrates with ← [[图床]]
## Related Concepts
- [[S3-兼容对象存储]]
- [[对象存储]]
- [[Docker堆栈]]

40
wiki/concepts/数据可视化.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: "数据可视化"
type: concept
aliases:
- Data Visualization
- 可视化分析
tags: [bi, data, visualization, charts, dashboards]
date: 2026-04-14
---
# 数据可视化
## Definition
**数据可视化**是将数据转换为图形、图表、地图等视觉表现形式的过程，旨在帮助用户快速理解数据模式、趋势和异常。涵盖范围从简单的静态图表到复杂的交互式仪表盘和实时数据流可视化。
## 核心原则
1. **准确性**: 视觉表示忠实反映数据，避免误导性缩放或截断
2. **清晰性**: 受众能快速理解图表含义，减少不必要的视觉元素
3. **相关性**: 选择最适合数据类型的图表形式（时序数据 → 折线图，分布 → 直方图，比例 → 饼图）
4. **可操作性**: 视觉化结果应驱动决策，而非仅为装饰
## 工具层次
| 层次 | 工具示例 | 特点 |
|------|----------|------|
| 监控告警 | [[Grafana]]、Datadog | 时序数据、告警驱动 |
| BI 分析 | [[Apache Superset]]、Metabase | SQL 优先、交互探索 |
| 嵌入式 | ECharts、Plotly | Web 集成、定制化 |
| 科学可视化 | Matplotlib、Plotly | 统计图表、学术用途 |
## Home Server 场景
在 Home Server 部署中，数据可视化主要服务两类场景：
1. **系统监控**: Prometheus + Grafana 监控服务器/容器状态
2. **业务分析**: Apache Superset 连接业务数据库做数据探索
## Related Concepts
- [[BI平台]]
- [[Prometheus]]
- [[Grafana]]
- [[Apache Superset]]

3
wiki/concepts/永久挂载.md
View File

@@ -78,6 +78,9 @@ fi
- [[NFS]] — 网络文件系统是永久挂载的典型应用
- [[挂载点检查]] — 备份前的安全检查机制
## Related Entities
- [[rsync]] — 永久挂载的典型使用场景：rsync 增量备份的目标存储
## See Also
- [[Cron定时任务]] — 永久挂载后自动执行备份
- [[进程管理]] — 网络断开时的进程控制

53
wiki/concepts/硬件转码.md Normal file
View File

@@ -0,0 +1,53 @@
---
title: "硬件转码"
type: concept
tags: [video, transcoding, hardware, jellyfin, performance]
date: 2026-04-14
---
# 硬件转码
通过 GPU 或专用硬件（而非 CPU 软件计算）加速视频编解码的过程。
## Core Mechanism
- 视频转码：将一种编码格式（如 H.265）转换为另一种（如 H.264）以适配不同客户端
- 软件转码：完全依赖 CPU 执行，计算密集，CPU 占用高
- 硬件转码：将编码计算卸载到 GPU/专用硬件单元，CPU 占用极低，速度快
## 常见硬件转码方案
| 方案 | 硬件 | 接口 | 常见应用 |
|------|------|------|----------|
| Intel QuickSync | Intel CPU 集成 GPU | /dev/dri | Jellyfin、FFmpeg |
| NVIDIA NVENC | NVIDIA 独立/移动 GPU | nvidia-container-toolkit | Jellyfin、Plex、FFmpeg |
| AMD VCE | AMD GPU | /dev/dri (DRI3) | FFmpeg |
| VA-API | 通用 Linux 视频加速 API | /dev/dri | FFmpeg、mpv |
| Apple VideoToolbox | Apple Silicon / Intel Mac | 框架调用 | macOS 原生应用 |
## Jellyfin 中的硬件转码
```yaml
devices:
- /dev/dri:/dev/dri # Intel QuickSync / VA-API
```
- 群晖 NAS 优先使用 QuickSync / VA-API 降低 CPU 占用
- nyanmisaka/jellyfin 镜像预装优化 FFmpeg，开箱即用 QuickSync
- 内存建议 2-4GB 以应对转码缓冲需求
## 性能对比（参考值）
| 方式 | 1080p H.265→H.264 转码（1小时） | CPU 占用 |
|------|-----------------------------------|----------|
| 软件转码（x264） | ~45 分钟 | 100%（多核） |
| Intel QuickSync | ~8 分钟 | ~15% |
| NVIDIA NVENC | ~5 分钟 | ~20% |
## Related Concepts
- [[设备直通]] — 将宿主机硬件设备映射到容器内使用，是硬件转码在 Docker 环境的前提
- [[软件转码]] — 无硬件加速时的 CPU 纯软件转码方案
- [[转码缓存]] — Jellyfin/Navidrome 中缓存已转码文件以避免重复转码
## Connections
- [[Jellyfin]] ← 应用场景 ← [[硬件转码]] — 媒体服务器转码加速
- [[Navidrome]] ← 应用场景 ← [[硬件转码]] — 音乐转码（音频转码）
- [[群晖 NAS]] ← 部署环境 ← [[硬件转码]] — Synology Intel CPU 支持 QuickSync
## Sources
- [[用docker安装jellyfin]] — 群晖 NAS 上 Jellyfin QuickSync 硬件转码配置

82
wiki/concepts/系统睡眠管理.md Normal file
View File

@@ -0,0 +1,82 @@
---
title: "系统睡眠管理"
type: concept
tags: [操作系统, 电源管理, 服务器运维]
---
# 系统睡眠管理
> 系统睡眠管理（Sytem Sleep Management）是操作系统在用户空闲时降低功耗的机制，包含多个层级的电源状态。服务器场景下通常需要禁用这些行为以确保持续可用性。
## 睡眠层级对比
| 层级 | macOS (pmset) | Linux (systemd-logind) | Windows |
|------|--------------|----------------------|---------|
| 显示器睡眠 | displaysleep | — | 显示器睡眠 |
| 系统空闲睡眠 | sleep | suspend | 睡眠 (S3) |
| 待机（延迟睡眠） | standby | suspend + timer | 睡眠 |
| 休眠（断电保存） | hibernatemode | hibernate | 休眠 (S4) |
| 混合睡眠 | — | hybrid-sleep | 混合睡眠 |
| 深度休眠 | — | suspend-then-hibernate | 快速启动 |
## macOS 睡眠管理
工具：`pmset`
| 参数 | 说明 |
|------|------|
| `sleep` | 系统空闲时进入睡眠（S3） |
| `displaysleep` | 显示器进入低功耗 |
| `standby` | 进入完全睡眠前的定时器（默认1小时） |
| `hibernatemode` | 内存内容写入磁盘后断电（S4） |
Home Server 配置：
```bash
sudo pmset -a sleep 0 displaysleep 0 standby 0 hibernatemode 0
```
## Linux 睡眠管理
工具：`systemd-logind` + `/etc/systemd/logind.conf`
| 参数 | 说明 |
|------|------|
| `HandleLidSwitch` | 合盖时动作（ignore/suspend/hibernate/lock） |
| `AllowSuspend` | 是否允许 suspend |
| `AllowHibernate` | 是否允许 hibernate |
进阶禁用：
```bash
systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
```
## 服务器场景的特殊性
1. **零物理交互**：无显示器/键盘，无法手动唤醒
2. **网络可用性要求**：持续可远程访问
3. **功耗容忍度**：始终接电，不依赖电池
4. **远程唤醒需求**：关机状态也需要 WoL 支持
## 跨平台对比
| 维度 | macOS | Ubuntu/Linux | 对应关系 |
|------|-------|-------------|---------|
| 基础禁用命令 | `pmset -a sleep 0` | `HandleLidSwitch=ignore` | sleep=HandleLidSwitch |
| 显示器睡眠 | `pmset -a displaysleep 0` | N/A（无显示器概念） | 无直接对应 |
| 待机定时器 | `pmset -a standby 0` | systemd-inhibit | 后台锁定机制 |
| 休眠模式 | `pmset -a hibernatemode 0` | `systemctl mask hibernate.target` | S4=hibernate |
| 网络唤醒 | `pmset -a womp 1` | ethtool wol g | 硬件+软件配合 |
## 相关概念
- [[pmset]] — macOS 睡眠管理工具
- [[caffeinate]] — macOS 临时防止睡眠
- [[Wake-on-LAN]] — 配合睡眠管理的远程唤醒
- [[systemd-logind]] — Linux 电源管理核心
- [[HandleLidSwitch]] — Linux 合盖动作配置
- [[休眠目标]] — Linux systemd 睡眠目标管理
## 相关实体
- [[Mac Mini M4]] — macOS 系统睡眠管理的典型应用场景
- [[Ubuntu Server]] — Linux 系统睡眠管理的典型应用场景

62
wiki/concepts/设备直通.md Normal file
View File

@@ -0,0 +1,62 @@
---
title: "设备直通"
type: concept
tags: [docker, hardware, device, passthrough, jellyfin]
date: 2026-04-14
---
# 设备直通
在容器化环境中将宿主机物理设备（GPU、声卡、硬件编码器等）映射到容器内，使容器内应用可直接访问和使用该硬件。
## Core Mechanism
Docker 容器默认运行在隔离的命名空间中，容器内无法直接访问宿主机的硬件设备。设备直通通过 `--device` 参数或 `devices` 配置项，将宿主机设备节点映射到容器内，使容器内进程可以像宿主机一样访问硬件。
## Docker 配置方式
```yaml
services:
jellyfin:
devices:
- /dev/dri:/dev/dri # Intel GPU / VA-API
- /dev/nvidia0:/dev/nvidia0 # NVIDIA GPU (需 nvidia-container-toolkit)
- /dev/snd:/dev/snd:rw # 声卡设备
```
## 常见使用场景
| 场景 | 宿主机设备 | 容器用途 |
|------|-----------|----------|
| Intel QuickSync 转码 | /dev/dri/renderD* | Jellyfin / FFmpeg 硬件视频转码 |
| NVIDIA 加速 | /dev/nvidia* | CUDA 计算、视频编码 |
| 声卡直通 | /dev/snd/* | 音频播放/录制 |
| 串口设备 | /dev/ttyUSB0 | 嵌入式设备调试 |
| GPU 直通（VM） | PCI 设备 | 游戏 / AI 推理 |
## Jellyfin 中的设备直通
```yaml
devices:
- /dev/dri:/dev/dri
```
- `/dev/dri` 是 Linux DRM（Direct Rendering Manager）设备目录
- 包含 renderD128/129 等节点，代表 GPU 渲染引擎
- Intel CPU 集成 GPU 通过此接口提供 QuickSync 视频编码
- VA-API 和 VDPAU 也依赖此接口
## 权限问题
- 默认情况下，容器以非 root 用户运行时可能无法访问 `/dev/dri`
- 解决方案：
1. 将设备映射为可读（`:ro`）
2. 在 `docker run` 时加上 `--group-add video`
3. 群晖 NAS 使用 `user: "1026:100"` 映射到有权限的用户
## Related Concepts
- [[硬件转码]] — 设备直通是硬件转码在 Docker 环境下的实现前提
- [[Docker 用户权限映射]] — 解决容器用户访问宿主机设备权限问题
- [[nvidia-container-toolkit]] — NVIDIA GPU 在 Docker 中的特殊设备直通方案
## Connections
- [[Jellyfin]] ← 受益应用 ← [[设备直通]] — QuickSync 硬件转码
- [[群晖 NAS]] ← 宿主机 ← [[设备直通]] — NAS Intel CPU GPU 访问
- [[Intel QuickSync]] ← 依赖 ← [[设备直通]] — GPU 硬件加速通道
## Sources
- [[用docker安装jellyfin]] — /dev/dri 设备直通的 Docker Compose 配置示例

143
wiki/concepts/逻辑备份.md Normal file
View File

@@ -0,0 +1,143 @@
---
title: 逻辑备份
type: concept
tags: [backup, postgresql, database]
date: 2025-12-29
---
# 逻辑备份
## Definition
逻辑备份是通过数据库工具导出数据为 SQL 语句或文本格式，而非直接复制物理数据文件。与物理备份相比，逻辑备份具有跨平台迁移能力强、不依赖特定存储格式的优势。
## PostgreSQL Logical Backup: pg_dump
### Core Command
```bash
# 基本语法
pg_dump -U username -d database_name > backup.sql
# Docker 环境（推荐）
docker exec zipline_postgres pg_dump -U zipline -d zipline > backup.sql
# 压缩格式（节省空间）
docker exec zipline_postgres pg_dump -U zipline -d zipline | gzip > backup.sql.gz
# 指定格式（自定义）
docker exec zipline_postgres pg_dump -U zipline -d zipline -Fc > backup.dump
```
### pg_dump Formats
| 格式 | 选项 | 说明 | 恢复灵活性 |
|------|------|------|------------|
| Plain SQL | `-Fp`（默认） | 纯文本 SQL，可跨版本 | 高（标准 SQL） |
| Custom | `-Fc` | 二进制压缩格式 | 中（需 pg_restore） |
| Directory | `-Fd` | 并行导出，多文件 | 高 |
| TAR | `-Ft` | TAR 归档格式 | 中 |
## Logical vs Physical Backup
| 特性 | 逻辑备份 | 物理备份 |
|------|----------|----------|
| 备份方式 | SQL 导出 | 直接复制数据文件 |
| 热备份 | ✅ 支持 | ⚠️ 需要额外配置 |
| 数据损坏风险 | 无 | 有（热备份时） |
| 跨版本迁移 | ✅ 完全支持 | ❌ 通常不行 |
| 备份速度 | 慢 | 快 |
| 恢复速度 | 慢 | 快 |
| 增量备份 | ❌ 不支持 | ✅ 支持 |
| 适用场景 | 跨平台迁移、小数据量 | 大数据量、灾难恢复 |
## Synology NAS Backup Script
```bash
#!/bin/bash
# Zipline Stack Backup Script
BACKUP_DIR="/volume1/docker/zipline-stack/backups"
PG_CONTAINER="zipline_postgres"
PG_USER="zipline"
PG_DB="zipline"
RETENTION_DAYS=30
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"
echo "[$DATE] 开始备份 Postgres..."
# pg_dump 逻辑备份（热备份）
# 注意：这里不直接备份 /var/lib/postgresql/data 目录
# 热备份该目录会导致数据损坏
docker exec "$PG_CONTAINER" pg_dump -U "$PG_USER" -d "$PG_DB" | gzip > "$BACKUP_DIR/db_$DATE.sql.gz"
if [ $? -eq 0 ]; then
echo "[$DATE] 数据库备份成功: db_$DATE.sql.gz"
else
echo "[$DATE] !!! 数据库备份失败 !!!"
exit 1
fi
# 清理旧备份
find "$BACKUP_DIR" -name "db_*.sql.gz" -mtime +$RETENTION_DAYS -delete
echo "[$DATE] 已清理超过 $RETENTION_DAYS 天的旧备份"
echo "[$DATE] 备份流程结束。"
```
## Key Principles
1. **禁止热备份物理目录**
> "不直接备份 /var/lib/postgresql/data 目录，因为热备份该目录会导致数据损坏"
2. **与文件备份配合**
- 逻辑备份：pg_dump → SQL 文件
- 文件备份：Hyper Backup → MinIO 数据目录
- 两者需尽量接近时间点备份
3. **自动化**
- Synology Task Scheduler：每日凌晨 3:00
- 日志输出：`>> backup.log 2>&1`
## "脑体分离" Architecture Challenge
[[Zipline]] 的备份挑战在于"脑体分离"：
```
大脑 (PostgreSQL) 身体 (MinIO)
│ │
▼ ▼
"文件A的ID是123， 实际存储了 a.jpg
位于MinIO的/bucket/a.jpg"
│ │
└──────── 需同步备份 ────────┘
```
**风险**：如果在 10:00 备份了数据库，10:05 备份了 MinIO，但这 5 分钟内上传了新文件，恢复时就会出现"数据库找不到文件"或"文件没记录"的幽灵数据。
**缓解方案**：尽量缩短两个备份的时间间隔，使用自动化脚本同时触发。
## Restore Commands
```bash
# 恢复 Plain SQL
gunzip < backup.sql.gz | psql -U username -d database_name
# 恢复 Custom Format
pg_restore -U username -d database_name -c backup.dump
# Docker 环境
cat backup.sql.gz | gunzip | docker exec -i zipline_postgres psql -U zipline -d zipline
```
## Connections
- [[PostgreSQL]] ← backed up by ← [[逻辑备份]]
- [[Zipline]] ← metadata stored in ← [[PostgreSQL]]
- [[pg_dump]] ← tool for ← [[逻辑备份]]
- [[数据一致性]] ← challenge of ← [[逻辑备份]] + 文件备份
## Related Concepts
- [[增量备份]]
- [[全盘镜像备份]]
- [[数据一致性]]
- [[备份脚本]]