Code &Flower

btop — 装完系统第一个 apt install 的终端资源监视器

Nywerya's blog — Sat, 13 Jun 2026 13:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/btop-system-monitor/

btop — 终端里的资源监视器

btop 是一个用 C++ 重写的系统资源监视器，可以看作 htop 的终极进化版。在终端里实时展示 CPU、内存、磁盘、网络、进程信息，界面精致、高度可定制。

和 htop / top 的区别

特性	top	htop	btop
界面	纯文本	彩色文本	全图形化 TUI（鼠标可点）
CPU 显示	数字	柱状条	每个核心独立折线图 + 颜色主题
内存/磁盘	数字	柱状条	柱状图 + 百分比 + 详细信息
网络	❌	❌	✅ 实时上下行速率图
进程树	❌	✅	✅
鼠标支持	❌	✅	✅
GPU 监控	❌	❌	✅ 部分支持
主题	❌	❌	✅ 内置多套主题

安装

Debian / Ubuntu

sudo apt install btop

Arch Linux

sudo pacman -S btop

Fedora

sudo dnf install btop

macOS

brew install btop

从源码编译

git clone https://github.com/aristocratos/btop.git
cd btop
make
sudo make install

基础操作

# 启动
btop

进入后直接用鼠标点击即可切换菜单，也可以用键盘：

按键	功能
`1` / `2` / `3` / `4`	切换到 CPU / 内存 / 磁盘 / 网络详细视图
`f`	进程过滤器（输入关键词筛选）
`t`	切换进程树模式
`m`	切换菜单栏显示
`Esc`	退出当前菜单 / 全局
`q` / `Ctrl+C`	退出 btop
`p`	切换进程排序方式
`+` / `-`	调整刷新间隔

配置主题

# 配置文件位置
~/.config/btop/btop.conf

预设主题切换：

btop --theme gruvbox_dark

btop --theme nord

btop --theme monokai

在配置文件中改主题：

# ~/.config/btop/btop.conf
color_theme = "gruvbox_dark"

其他常用配置：

# 刷新间隔（毫秒）
update_ms = 1000

# 显示温度
show_cpu_temp = True

# 图表背景
theme_background = False

# 网络图表自动缩放
net_auto = True

实用场景

排查 CPU 瓶颈

编译大项目时开一个 btop，每个核心的折线图一眼看出是不是有单核瓶颈：

# 终端 1：编译
make -j$(nproc)

# 终端 2：监控
btop

监控磁盘 IO

# 按 3 切换到磁盘视图
# 能看出哪个进程在大量读写

排查内存泄漏

# 按 m 打开菜单 → 进程按内存排序
# 看哪个进程内存持续增长

网络流量监控

# 按 4 切换到网络视图
# 显示每个网络接口的实时收发速率

远程服务器常驻

# SSH 到服务器后直接跑
ssh user@server -t btop

# 或者在 tmux 里常驻一个面板
tmux split-window -h btop

进阶技巧

快捷键绑定别名

# ~/.bashrc 或 ~/.zshrc
alias top='btop'

从此敲 top 就是 btop。

进程信号

btop 里选中进程后可以直接发送信号（T 键），支持 SIGTERM、SIGKILL、SIGSTOP 等，不用再开一个终端 kill。

预设布局

# 启动时直接进入指定视图
btop --preset cpu      # 只看 CPU
btop --preset net      # 只看网络
btop --preset proc     # 只看进程

总结

btop 在我所有 Linux 机器上都是装完系统第一个 apt install 的东西。相比 htop 的优势不只是好看——网络监控和磁盘 IO 面板在很多排查场景里能省掉另外开 iftop / iotop 的步骤。而且鼠标可点，对不熟命令行的人也更友好。

N2N 虚拟局域网搭建 — 一键脚本 + 联机游戏实战

Nywerya's blog — Fri, 12 Jun 2026 13:20:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/n2n-virtual-lan-setup/

N2N 虚拟局域网搭建

为什么搭虚拟局域网

和朋友联机玩以撒的结合，被土豆服务器折磨到无言。以撒的联机不同于泰拉瑞亚与 MC，无法使用 IP 直连，内网穿透（frp）也无能为力——只能上虚拟局域网。

原理：将不同局域网的用户通过中转节点（Supernode）形成一个模拟的局域网，功能等效于物理局域网，支持所有局域网联机游戏。以撒和饥荒这类游戏的联机方式虽然不能选"局域网联机"，但会自动找到最优网络路径，刚打通的虚拟局域网也在其中。

服务端

服务器操作系统：Ubuntu 24.04

安装 N2N

# 更新 apt
sudo apt update
apt install cmake

# 下载 v3.1.1 稳定版
cd /tmp
rm -rf n2n
git clone https://github.com/ntop/n2n.git
cd n2n
git checkout 3.1.1

# 编译安装
mkdir build && cd build
cmake ..
make -j4
sudo make install

# 验证
/usr/local/bin/edge --version
/usr/local/bin/supernode --version

# 创建符号链接
sudo ln -sf /usr/local/bin/edge /usr/bin/edge
sudo ln -sf /usr/local/bin/supernode /usr/bin/supernode

配置 Supernode（超级节点）

# 创建配置文件
sudo sh -c 'cat > /etc/n2n/supernode.conf << "EOF"
-p=7654
-m=5645
-f=/etc/n2n/communities.list
-l=/var/log/n2n/supernode.log
-r
EOF'

创建 systemd 服务：

sudo sh -c 'cat > /etc/systemd/system/n2n-supernode.service << "EOF"
[Unit]
Description=N2N Supernode v3.1.1
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/sbin/supernode -p 7654 -f -i 203.0.113.1
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
EOF'

启动：

sudo systemctl daemon-reload
sudo systemctl start n2n-supernode
sudo systemctl enable n2n-supernode

检查运行状态：

sudo systemctl status n2n-supernode --no-pager
sudo netstat -tulnp | grep 7654
ps aux | grep supernode
sudo journalctl -u n2n-supernode -f --no-pager

服务器配置 Edge（服务器也要加入网络）

sudo sh -c 'cat > /etc/systemd/system/n2n-edge.service << "EOF"
[Unit]
Description=N2N Edge Client v3.1.1
After=network.target n2n-supernode.service
Wants=n2n-supernode.service

[Service]
Type=simple
ExecStart=/usr/local/sbin/edge -d n2n0 -a 10.0.0.1 -c mycommunity -k mysecretkey -l 127.0.0.1:7654 -f
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
EOF'

sudo systemctl daemon-reload
sudo systemctl start n2n-edge
sudo systemctl enable n2n-edge

检查与调试

# 检查 edge 进程
ps aux | grep edge

# 查看网卡
ip link show | grep n2n

# 监听端口
sudo tcpdump -i any udp port 7654 -vv -n

# 查看日志
sudo journalctl -u n2n-supernode -n 50

客户端

使用 EasyN2N 软件：

在自定义服务器内填写服务器 IP 和端口
填写小组名称（与服务器 -c 参数一致）
在软件设置中添加密钥附加参数：

-k mysecretkey

连接即可

直连命令（不用 EasyN2N）

# 基本直连
edge -a 10.0.0.10 -c mycommunity -k mysecretkey -l 203.0.113.1:7654 -d n2n1

# 如果使用端口映射
edge -a 10.0.0.10 -c mycommunity -k mysecretkey -l example.com:54332 -d n2n1

一键安装脚本

需要一台云服务器（2c2g 够用，1c0.5g 也能跑，重要的是网速≥1Mbps）。

#!/bin/bash
# feat: 一键部署 n2n 局域网
# 系统要求: Ubuntu 24.04
# 网络要求: 能使用 apt 安装软件包, 能 git 抓取 github 文件

LOG_FILE="/var/log/n2n-deploy.log"
N2N_VERSION="3.1.1"
SUPERNODE_PORT=7654
EDGE_IP="10.0.0.1"
COMMUNITY="mycommunity"
SECRET_KEY="mysecretkey"  # 请换成自己的密钥！

# 停止已有服务
sudo systemctl stop n2n-supernode n2n-edge 2>/dev/null

# 日志函数
log() {
    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"
}

error_exit() {
    log "错误: $*"
    exit 1
}

# 检查是否为 root
if [ $EUID -ne 0 ]; then
    error_exit "此脚本必须以 root 权限运行！请使用 sudo。"
fi

log "开始部署 n2n v$N2N_VERSION..."

# 更新 apt 并安装依赖
log "更新 apt 并安装必要工具..."
apt update >> "$LOG_FILE" 2>&1 || error_exit "apt update 失败"
apt install -y cmake git build-essential >> "$LOG_FILE" 2>&1 || error_exit "安装依赖失败"

# 安装 n2n
echo "是否需要安装 n2n? (y/n)"
read choice
if [ "$choice" = "y" ] || [ "$choice" = "Y" ]; then
  cd /tmp || error_exit "无法进入 /tmp 目录"
  log "清理旧的 n2n 目录..."
  rm -rf n2n

  log "克隆 n2n 仓库..."
  git clone https://github.com/ntop/n2n.git >> "$LOG_FILE" 2>&1 || error_exit "git clone 失败"
  cd n2n || error_exit "无法进入 n2n 目录"

  log "切换到版本 $N2N_VERSION..."
  git checkout "$N2N_VERSION" >> "$LOG_FILE" 2>&1 || error_exit "无法切换到 tag $N2N_VERSION"

  log "配置并编译 n2n..."
  mkdir -p build && cd build || error_exit "无法创建 build 目录"
  cmake .. >> "$LOG_FILE" 2>&1 || error_exit "cmake 配置失败"
  make -j$(nproc) >> "$LOG_FILE" 2>&1 || error_exit "编译失败"

  log "安装 n2n..."
  make install >> "$LOG_FILE" 2>&1 || error_exit "安装失败"

  ln -sf /usr/local/bin/edge /usr/bin/edge
  ln -sf /usr/local/bin/supernode /usr/bin/supernode
fi

# 创建配置目录
mkdir -p /etc/n2n /var/log/n2n

# 写入 supernode 配置
log "写入 supernode 配置..."
cat > /etc/n2n/supernode.conf <<EOF || error_exit "写入 supernode.conf 失败"
-p=$SUPERNODE_PORT
-m=5645
-f=/etc/n2n/communities.list
-l=/var/log/n2n/supernode.log
-r
EOF

# 写入 supernode systemd 服务
log "创建 supernode systemd 服务..."
cat > /etc/systemd/system/n2n-supernode.service <<EOF || error_exit "创建 supernode service 失败"
[Unit]
Description=N2N Supernode v$N2N_VERSION
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/sbin/supernode -p $SUPERNODE_PORT -f
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
EOF

# 写入 edge systemd 服务
log "创建 edge systemd 服务..."
cat > /etc/systemd/system/n2n-edge.service <<EOF || error_exit "创建 edge service 失败"
[Unit]
Description=N2N Edge Client v$N2N_VERSION
After=network.target n2n-supernode.service
Wants=n2n-supernode.service

[Service]
Type=simple
ExecStart=/usr/local/sbin/edge -a $EDGE_IP -c $COMMUNITY -l 127.0.0.1:$SUPERNODE_PORT -d n2n0 -k $SECRET_KEY -f
Restart=always
RestartSec=10
User=root

[Install]
WantedBy=multi-user.target
EOF

# 重载 systemd
log "重载 systemd 配置..."
systemctl daemon-reload >> "$LOG_FILE" 2>&1 || error_exit "systemctl daemon-reload 失败"

# 启动服务
log "启动 n2n-supernode 服务..."
systemctl start n2n-supernode >> "$LOG_FILE" 2>&1 || error_exit "启动 supernode 失败"

log "启动 n2n-edge 服务..."
systemctl start n2n-edge >> "$LOG_FILE" 2>&1 || error_exit "启动 edge 失败"

# 启用开机自启
log "启用开机自启动..."
systemctl enable n2n-supernode n2n-edge >> "$LOG_FILE" 2>&1 || error_exit "启用自启动失败"

log "n2n 部署完成！supernode 运行在端口 $SUPERNODE_PORT，edge IP: $EDGE_IP"
echo "社区名: $COMMUNITY"
echo "密钥: $SECRET_KEY （请妥善保存！）"
echo "请使用服务器公网 IP + 7654 端口连接，加上社区和密钥参数"
echo "部署成功后无需再次运行此脚本！"
echo "日志位置: $LOG_FILE"

常用管理命令

# 停止服务
sudo systemctl stop n2n-supernode n2n-edge

# 重启服务
sudo systemctl restart n2n-supernode n2n-edge

# 查看状态
sudo systemctl status n2n-supernode --no-pager
sudo systemctl status n2n-edge --no-pager

# 防火墙放行
sudo ufw allow 7654/udp

总结

服务端：Supernode 作为中转节点，Edge 让服务器自己也加入网络
客户端：EasyN2N 图形化连接，填 IP + 社区名 + 密钥即可
适用游戏：以撒的结合、饥荒等不支持 IP 直连的局域网游戏
成本：一台最低配云服务器就行，重要的是带宽

one-api 中转站搭建教程 — 聚合 API 赚差价

Nywerya's blog — Fri, 12 Jun 2026 13:20:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/one-api-proxy-setup/

one-api 中转站搭建教程

API 中转站的核心思路：你有上游 API Key（DeepSeek/OpenAI/Claude），下游用户通过你中转调用，你赚差价。

开源项目 one-api 帮你搞定：聚合多平台 API → 统一管理 → 生成子 Key → 按量计费。

一、你需要什么

资源	说明
一台服务器	轻量云 ¥50-100/月（阿里云/腾讯云），1核2G 够用
一个域名	用于中转站访问（api.你的域名.com），可选
上游 API Key	DeepSeek 官网注册送额度，或找上游渠道
Docker 环境	服务器上装好 Docker + docker-compose

二、服务器初始化

SSH 登录后：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装 Docker
curl -fsSL https://get.docker.com | sudo bash
sudo usermod -aG docker $USER

# 安装 docker-compose
sudo apt install docker-compose -y

# 防火墙只开 80/443/22
sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable

# 重新登录使 docker 权限生效
exit

三、部署 one-api

3.1 Docker 一键启动

docker run -d \
  --name one-api \
  --restart always \
  -p 3000:3000 \
  -v /opt/one-api/data:/data \
  -e TZ=Asia/Shanghai \
  justsong/one-api

验证：

docker ps | grep one-api
curl http://localhost:3000
# 应返回 one-api 的 HTML 页面

3.2 配置 Nginx 反代 + SSL（如果有域名）

sudo nano /etc/nginx/sites-available/api

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d api.example.com

3.3 初始登录

浏览器打开 http://你的服务器IP:3000 或 https://api.example.com

默认账号：root
默认密码：123456
登录后第一件事：改密码！ 右上角头像 → 修改密码

四、配置渠道（接入上游 API）

4.1 添加 DeepSeek 渠道

渠道 → 添加渠道：

字段	值
类型	DeepSeek
名称	DeepSeek
分组	default
模型	`deepseek-chat`, `deepseek-reasoner`
密钥	你的 DeepSeek API Key
代理	留空（除非需要反代地址）

4.2 添加 OpenAI 渠道（可选）

字段	值
类型	OpenAI
名称	OpenAI
分组	default
模型	`gpt-4o`, `gpt-4o-mini`
密钥	你的 OpenAI API Key

4.3 添加 Claude 渠道（可选，需反代）

Claude API 对国内 IP 不友好，需要反代。在代理栏填反代地址，或通过 Cloudflare Workers 中转（见第七节）。

4.4 添加自定义渠道（对接其他中转站）

如果你的上游也是中转站（兼容 OpenAI 格式）：

字段	值
类型	自定义渠道
名称	上游中转
分组	default
模型	`gpt-4o`, `claude-sonnet-4-6` 等
密钥	上游给的 Key
代理	上游中转站的 API 地址

五、定价策略：设置倍率

5.1 模型倍率设置

模型 pricing → 编辑每个模型的倍率：

DeepSeek 官方价格：输入 ¥1 / 百万 token
倍率设为 2.0：用户付费 ¥2 / 百万 token
你的毛利：¥1 / 百万 token（成本 ¥1，收 ¥2）

建议倍率：

模型	官方价（约）	建议倍率	用户价（约）
DeepSeek Chat	¥1/M	1.5-2.0	¥1.5-2/M
DeepSeek Reasoner	¥4/M	1.5-2.0	¥6-8/M
GPT-4o	¥35/M	1.3-1.5	¥45-52/M
Claude Sonnet	¥45/M	1.3-1.5	¥58-67/M

低价模型用高倍率：DeepSeek 本身便宜，用户对 ¥1 和 ¥2 不敏感，2 倍就是 100% 毛利
高价模型用低倍率：GPT/Claude 单价高，倍率高了用户会被吓跑

5.2 用户分组（差异化定价）

可以为不同用户设置不同分组，每个分组对应不同倍率：

default 分组：标准价格（倍率 2.0）
vip 分组：大客户优惠（倍率 1.5）
trial 分组：体验组（倍率 1.0，不赚钱，纯引流）

六、生成用户 Key

用户 → 添加用户 → 生成 Key：

填写用户名（客户昵称）
设置额度（如 ¥50）
选择分组（default / vip）
生成 → 复制 Key 发给客户

客户拿到 Key 后，在 Claude Code / Cursor 等工具里配置 API 地址和 Key 就能用。

API 地址：https://api.example.com/v1（兼容 OpenAI 格式）

七、零成本方案：Cloudflare Workers

如果暂时不想买服务器，用 Cloudflare Workers 免费搭反代：

7.1 创建 Worker

export default {
  async fetch(request) {
    const url = new URL(request.url);
    
    // 反代到 DeepSeek API
    const targetUrl = "https://api.deepseek.com" + url.pathname;
    
    // 验证用户 Key（简单鉴权）
    const userKey = request.headers.get("Authorization");
    const VALID_KEYS = ["sk-user1-xxx", "sk-user2-yyy"];
    
    if (!userKey || !VALID_KEYS.includes(userKey.replace("Bearer ", ""))) {
      return new Response("Unauthorized", { status: 401 });
    }
    
    // 替换为你的 DeepSeek Key
    const newHeaders = new Headers(request.headers);
    newHeaders.set("Authorization", "Bearer sk-your-deepseek-key");
    
    return fetch(targetUrl, {
      method: request.method,
      headers: newHeaders,
      body: request.body
    });
  }
};

7.2 绑定自定义域名

Worker → 设置 → 触发器 → 自定义域 → 添加 api.example.com

7.3 局限性

Workers 免费版每天 10 万次请求，个人用够
只能反代一个上游，不能像 one-api 聚合多平台
没有额度管理系统，需要手动计费
适合起步验证需求，确认有客户了再升级到 one-api

八、运维要点

8.1 监控余额

one-api 后台 → 渠道 → 点击「测试」检查上游 Key 是否有效。建议每周检查一次余额。

8.2 备份数据

# one-api 数据在 /opt/one-api/data/
tar -czf one-api-backup-$(date +%Y%m%d).tar.gz /opt/one-api/data/

8.3 防止滥用

单用户设置额度上限（如 ¥200）
发现异常调用立刻禁用 Key
在用户协议里写明「禁止自动化批量调用」

8.4 多账号分散风险

DeepSeek 一个账号免费额度有限。如果客户量大：多注册几个 DeepSeek 账号，在 one-api 里添加多个同类型渠道，自动负载均衡。

九、成本收益估算

项目	月成本
轻量云服务器	¥50-100
域名（年付）	¥20-50/年 ≈ ¥2-4/月
上游 API 成本	看客户用量

假设有 10 个稳定客户，每人月均消耗 ¥50 的 API：

月流水：10 × ¥50 = ¥500
上游成本（倍率 2.0）：¥250
毛利：¥500 - ¥250 - ¥100（服务器）= ¥150/月

客户越多，固定成本摊得越薄。30 个客户时毛利超过 ¥500/月。

十、升级路径

起步：Cloudflare Worker 免费方案，验证有客户愿意付费
有稳定 5-10 个客户后：上服务器 + one-api，正规化管理
规模化：多上游 → 自动负载均衡 → 监控告警 → 自动充值

关键是先验证需求再投入，不要服务器买了一堆没客户。

自建图床：Syncthing + Nginx 零成本图片 CDN

Nywerya's blog — Fri, 12 Jun 2026 12:30:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/self-host-image-cdn/

自建图床：Syncthing + Nginx

思路

本地 Vault 图片  ──Syncthing──▶  服务器 /var/www/photo/  ──Nginx──▶  photo.example.com/xxx.png

本地写完笔记直接丢图到 vault 里，Syncthing 自动推到服务器，Nginx 提供公网访问。写作流程零改变。

重点：保留了 vault 的文件结构，只需要添加链接头即可访问。

第一步：服务器准备

1.1 创建图片目录 + 占位页

sudo mkdir -p /var/www/photo
sudo chown $USER:$USER /var/www/photo

# 占位页面，避免空目录 403
cat > /var/www/photo/index.html << 'EOF'
<!DOCTYPE html>
<html lang="zh">
<head><meta charset="UTF-8"><title>Photo</title></head>
<body><h1>Photo CDN</h1></body>
</html>
EOF

1.2 配置 Nginx（先 80，不要写 SSL）

sudo nano /etc/nginx/sites-available/photo

server {
    listen 80;
    server_name photo.example.com;

    root /var/www/photo;
    index index.html;

    # 允许跨域（博客站点引用图片）
    add_header Access-Control-Allow-Origin "*";

    # 图片缓存 1 年
    location ~* \.(png|jpg|jpeg|webp|gif|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

sudo ln -s /etc/nginx/sites-available/photo /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

1.3 DNS + Certbot 自动升级 HTTPS

DNS 先加 A 记录：photo → 203.0.113.1，生效后：

sudo certbot --nginx -d photo.example.com

Certbot 会自动：

申请证书
把 listen 80 改为 listen 443 ssl
补上 ssl_certificate / ssl_certificate_key 路径

关键：不要手写 SSL 配置——证书还不存在时 nginx 配置校验会失败，certbot 也无法运行。先 listen 80，让 certbot 自己升级。

第二步：Syncthing 同步

2.1 添加共享目录

在服务器 Syncthing 的 GUI 中：

添加文件夹 → 路径填 /var/www/photo
文件夹 ID 随意，如 photo-cdn
在「共享」选项卡，选择你的本地电脑

2.2 本地电脑接受

本地 Syncthing 收到共享请求后，路径选 vault 的图片目录，接受。

2.3 筛选同步（.stignore）

在服务器 /var/www/photo/.stignore 里创建：

# 不同步 Syncthing 冲突文件
.sync-conflict-*

# 不同步临时文件
*.tmp
*.temp
~$*

# 只同步图片
!*.png
!*.jpg
!*.jpeg
!*.webp
!*.gif
!*.svg
!*.ico

# 默认拒绝
*

.stignore 的规则：! 是允许，* 是拒绝所有。上面意思是"只同步图片文件"。

第三步：与 Obsidian 写作流程对接

3.1 本地写文章时

仍然用 Obsidian 的 wiki 链接：

![[笔记/工具软件/CopyQ/data/注释/screenshot.png]]

3.2 发布时替换链接

发布到博客时，将 ![[...]] 替换为 Markdown 标准格式：

![screenshot](https://photo.example.com/笔记/CopyQ/data/注释/screenshot.png)

转换规则：去掉 [[-]]，加上 https://photo.example.com/ 前缀。

第四步：验证

# 服务器放一张测试图
touch /var/www/photo/test.png

# 公网可达性
curl -s -o /dev/null -w "%{http_code}" https://photo.example.com/test.png
# 应返回 200

# 缓存头
curl -I https://photo.example.com/test.png 2>/dev/null | grep -i cache
# Cache-Control: public, immutable

优缺点

维度	评价
成本	✅ 用已有服务器，零额外支出
速度	⚠️ 家用服务器上行带宽有限（10-30Mbps），大图加载慢
维护	⚠️ 需要维护 Nginx + Syncthing + SSL 证书
CDN	❌ 无 CDN，全国/全球访问不如云对象存储
写作体验	✅ 零改变——扔图进 vault，自动同步
数据安全	✅ 数据全在手里，不怕图床跑路

如果后续图片多了、访问慢了，可以升级到 Cloudflare R2（配合 PicGo），Syncthing + Nginx 作为起步方案够用。

Umami 网站统计部署指南 — 15 分钟自建隐私友好分析

Nywerya's blog — Fri, 12 Jun 2026 12:30:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/self-host-umami-analytics/

Umami 自建网站统计

这是什么

Umami 是开源的网站访问统计工具，Google Analytics 的轻量替代品。部署在自己的服务器上，数据归你，不会追踪用户隐私。

对比 GA4：Umami 部署 5 分钟，打开 dashboard 就能看懂，不用考 GA 分析师证。

效果展示

博客底部的"阅读量"就是 Umami 提供的：

┌──────────────────────────────────┐
│ 📊 站点统计                        │
│ 👁 总 PV：12,345                  │
│ 👥 总 UV：4,567                   │
│ 📈 今日 PV：123                   │
└──────────────────────────────────┘

每个文章页面显示单篇浏览量，ProfileBar 展示全站实时统计。

部署架构

Umami 是 Node.js 应用，需要 Postgres 或 MySQL 数据库。用 Docker Compose 一把梭：

blog.example.com  ──→  Cloudflare Pages (Astro 静态页面)
                          │
                          ├─ <script> 加载 umami.example.com/script.js
                          │
umami.example.com  ──→  云服务器 (203.0.113.1)
                          │
                          ├─ Nginx (反代 + SSL)
                          │   └─ proxy_pass → localhost:3000
                          │
                          └─ Docker Compose
                              ├─ umami (Node.js, port 3000)
                              └─ postgres (port 5432)

第一步：Docker Compose 部署 Umami

在服务器上找一个目录，比如 ~/umami/，创建 docker-compose.yml：

version: '3'
services:
  umami:
    image: ghcr.nju.edu.cn/umami-software/umami:postgresql-latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:example-db-password@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: example-app-secret-replace-with-openssl-rand
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: example-db-password
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

数据库密码和 APP_SECRET 换成你自己的。APP_SECRET 跑个 openssl rand -hex 32 生成。

# 启动
docker-compose up -d

# 确认跑起来了
docker-compose ps
# 应该看到两个容器都是 Up 状态

第二步：Nginx 反代 + SSL

Umami 跑在 localhost:3000，用一个子域名反代出去。在 /etc/nginx/sites-available/ 中创建 umami：

server {
    listen 80;
    server_name umami.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

记得配置 DNS，然后启用并上 SSL。

不要直接用 certbot --nginx — 它有概率把 SSL 配置写进 default 文件，导致 403。用更稳的 certonly 方式：

# 先启用 site（一定要在 certbot 之前做）
sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/

# 只申请证书，不动 nginx 配置
sudo certbot certonly --nginx -d umami.example.com

证书拿到后，补完整 SSL 配置：

server {
    listen 80;
    server_name umami.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name umami.example.com;
    ssl_certificate /etc/letsencrypt/live/umami.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/umami.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo nginx -t && sudo systemctl reload nginx

为什么不直接用 `certbot --nginx`

certbot --nginx 会自动修改 nginx 配置加 SSL，但它判断"改哪个文件"的逻辑有问题 — 如果 default 里有 listen 80，它可能把 SSL block 写进 default 而不是你的独立配置文件。结果就是：443 请求命中 default 的静态文件 root，反代没生效，返回 403。

第三步：在 Umami 添加网站

浏览器打开 https://umami.example.com
用刚创建的管理员账号登录
Settings → Websites → Add website
Name 随便填，Domain 填你博客域名
创建后拿到 Website ID（一串 UUID）

第四步：博客集成

在 ryuchan.config.yaml 里填：

umami:
  enable: true
  baseUrl: https://umami.example.com
  websiteId: your-website-id-here
  shareId: ""
  timezone: Asia/Shanghai

部署后 F12 → Network，应该能看到 /script.js 请求。

第五步：开启分享

博客底部的 PV/UV 数字需要开分享功能：

Umami 后台 → Settings → Websites → 点你的网站
Share → Enable share URL
填入密码，保存后得到分享 URL
URL 中那段随机字符串就是 shareId，填进 ryuchan.config.yaml

原理

Umami Share API 不需要认证 token：

请求 /api/share/{shareId} 获取临时 token
带 token 请求 /api/websites/{websiteId}/stats 拉数据
结果缓存 1 小时（localStorage）

不想自建？用 Umami Cloud

打开 cloud.umami.is
注册账号，添加网站，拿 Website ID
baseUrl 填 https://cloud.umami.is

免费版 3 个网站 + 无限事件，个人博客够用。

实操要点

端口只绑 127.0.0.1：Umami 容器别暴露到公网
数据库持久化：./pgdata 映射出来
首次访问直接注册：打开网页创建管理员账号
定期备份：pg_dump 或直接备份 ./pgdata 目录
APP_SECRET 很重要：session 加密密钥，丢了所有登录失效

Syncthing 部署与配置指南

Nywerya's blog — Thu, 11 Jun 2026 21:15:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/p2p-file-sync-setup/

Syncthing 部署与配置指南

Syncthing 是一款开源的连续文件同步工具，P2P 架构，无需中心服务器。本文记录在云服务器上部署 Syncthing 并配置 Nginx 反代的全过程。

GUI 访问

GUI 默认监听 127.0.0.1:8384（仅本地）。不要改为 0.0.0.0——走 Nginx 反代更安全。

临时：SSH 隧道

ssh -L 8384:127.0.0.1:8384 root@服务器IP -N

浏览器 http://127.0.0.1:8384。

长期：Nginx 反代 + HTTPS

sudo nano /etc/nginx/sites-available/syncthing

server {
    listen 443 ssl;
    server_name sync.example.com;

    ssl_certificate     /etc/letsencrypt/live/sync.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sync.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8384;
        proxy_http_version 1.1;
        proxy_set_header Host 127.0.0.1:8384;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

sudo ln -s /etc/nginx/sites-available/syncthing /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

DNS 添加 A 记录 sync → 203.0.113.1，certbot 申请证书：

sudo certbot --nginx -d sync.example.com

踩坑：403 Forbidden

直接访问 127.0.0.1:8384 返回 200，但通过域名返回 403。两个原因叠加：

序号	原因	现象	修复
1	Certbot 生成的 server block 是静态文件服务器（`root` + `try_files`），不是反代	nginx 尝试从 `/var/www/html` 找文件，找不到返回 403	改为 `proxy_pass http://127.0.0.1:8384`
2	Syncthing 的 CSRF Host 校验拒绝域名头	改了反代后依然 403	`proxy_set_header Host 127.0.0.1:8384`（传 Syncthing 自己监听的地址）

关键：Host 头不能传 $host（域名），必须传 127.0.0.1:8384，Syncthing 才认。

同步端口

防火墙

sudo ufw allow 22000/tcp
sudo ufw allow 21027/udp

阿里云安全组

端口	协议	授权
22000	TCP	0.0.0.0/0
21027	UDP	0.0.0.0/0

监听地址

GUI 仅本地，同步端口监听所有接口：

<!-- ~/.local/state/syncthing/config.xml -->
<gui enabled="true" tls="false">
    <address>127.0.0.1:8384</address>
</gui>
<options>
    <listenAddress>tcp://0.0.0.0:22000</listenAddress>
</options>

NAT 穿透验证

云服务器无 UPnP（Detected NAT services: count=0 正常）。开端口后确认直连：

# 看日志：不应再有 "Joined relay"
journalctl -u syncthing -f | grep -i relay
# 应出现 quic://公网IP:22000，不再走 relay

设置访问密码

<gui enabled="true" tls="false">
    <address>127.0.0.1:8384</address>
    <user>admin</user>
    <password>example-password</password>
</gui>

密码会在下次启动时自动哈希。

开机自启

mkdir -p ~/.config/systemd/user

# ~/.config/systemd/user/syncthing.service
[Unit]
Description=Syncthing - Open Source Continuous File Synchronization
Documentation=man:syncthing(1)
After=network.target

[Service]
ExecStart=/usr/local/bin/syncthing -no-browser -gui-address=127.0.0.1:8384 -logflags=0
Restart=on-failure
RestartSec=10
UMask=0027
Environment=STNORESTART=1

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable syncthing.service
systemctl --user start syncthing.service
systemctl --user status syncthing.service

诊断命令

# GUI 监听
ss -tlnp | grep 8384

# 同步端口
ss -tlnp | grep 22000

# 外部可达性
nc -zv 203.0.113.1 22000

# GUI 可达性
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8384
curl -s -o /dev/null -w "%{http_code}" https://sync.example.com

# 实时日志
journalctl -u syncthing -f

# 检查 relay 状态（无输出=直连成功）
journalctl -u syncthing --since "5 min ago" | grep "Joined relay"

GNOME 剪贴板管理器 Clipboard Indicator — 原生 · 高响应 · 安全

Nywerya's blog — Thu, 04 Jun 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/gnome-clipboard-indicator/

痛点

GNOME 桌面默认的剪贴板只有**「最后一次复制」**的内容。前脚复制了一段代码，后脚不小心 Ctrl+C 了个空行 — 刚才那段话就没了。

Windows 有 Win+V 剪贴板历史，macOS 有第三方工具，GNOME 呢？靠插件。

Clipboard Indicator

Clipboard Indicator 是 GNOME Extensions 上下载量最高的剪贴板管理插件（200 万+），由 Tudmotu 开发维护，支持 GNOME 3.36 ~ 50。

为什么选它？三个词：原生、高响应、安全。

原生：长在 GNOME 身上

Clipboard Indicator 是一个 GNOME Shell Extension，不是独立 App。

这意味着：

零寄生依赖 — 它跑在 GNOME Shell 进程里，用 GNOME 原生的 JS 运行时，不依赖 Electron、不依赖 Python 环境、不需要独立守护进程
原生面板集成 — 图标直接嵌入顶部 panel，不走系统托盘（GNOME 本来也没有托盘），和时钟、网络、音量图标平起平坐
原生 UI 风格 — 下拉菜单、搜索框、设置窗口全部走 GNOME 系统主题，开深色模式自动跟随，不会出现 GTK 和 Qt 混搭的割裂感
原生扩展管理 — 用系统自带的 Extensions 应用就能配置、开关、升级，没有额外的后台管理界面

做个不严谨的类比：CopyQ 像是装了个第三方输入法，Clipboard Indicator 像是系统输入法自带的功能增强 — 前者功能更强，后者毫无存在感。

高响应：不让你等

剪贴板管理器有个反直觉的要求：你必须比 Ctrl+V 还快，才有存在意义。

如果按下快捷键后菜单弹出要卡半秒，人会下意识放弃它，继续用 Ctrl+V 完事。

Clipboard Indicator 做到了：

即时弹出 — 按下快捷键，菜单即刻出现。原因是它只用 GNOME Shell 原生 API，没有跨进程通信，没有 DBus 来回，所有数据在内存里
即搜即得 — 历史列表内直接打字搜索，无索引重建、无后台扫描，就是简单的前端文本匹配
常驻内存但不吃资源 — 作为 GNOME Shell 扩展运行，不需要额外进程、不轮询剪贴板（用 GNOME 的信号机制被动接收复制事件），闲置时 CPU 占用趋近于零
图片也流畅 — 少数支持剪贴板图片历史的 GNOME 管理器，预览、粘贴图片不卡顿

装了跟没装一样的性能开销，但关键时刻按一下 Super+V，半年前复制的那段命令还能找回来。

安全：剪贴板数据不出机器

剪贴板是桌面上最敏感的数据通道之一。密码、Token、私钥、API Key、身份证号 — 都可能经过剪贴板。

Clipboard Indicator 在安全上做对了三件事：

① 数据完全本地

不联网、不请求任何远程 API、不上传任何数据
历史记录只存在内存中，重启后清空（不会写入磁盘）
代码开源在 GitHub，审过再说

② 隐私模式 — 一键暂停记录

进入隐私模式后，复制的内容不会进入历史。临时处理敏感信息时打开，做完关掉 — 密码、银行卡号之类的东西不会留在列表里。

③ 随时可清

右键菜单 → Clear history，所有历史一键清空。没有「软删除」，没有「回收站」，数据即刻消失。

相比某些剪贴板管理器会把历史存到 SQLite 甚至同步到云端，Clipboard Indicator 的安全模型简单粗暴：你的剪贴板只属于你的内存，关机即清零。

核心功能速览

剪贴板历史

自动记录文本 + 图片
可设缓存条数上限
支持搜索

内容置顶

右键 Pin 到顶部，适合固定邮箱地址、Git commit 模板、代码片段。

全键盘操作

按键	功能
`↑` `↓`	浏览
`Enter`	粘贴
`Delete`	删除
`p`	置顶/取消

其他

粘贴后自动关闭菜单
可自定义快捷键（默认 Super+V）
面板图标可换

安装

方式一：网页一键

extensions.gnome.org/extension/779 → 点右上角开关。

开关灰色？先装浏览器连接器：
sudo apt install chrome-gnome-shell

方式二：包管理器

# Debian / Ubuntu
sudo apt install gnome-shell-extension-clipboard-indicator

# Fedora
sudo dnf install gnome-shell-extension-clipboard-indicator

# Arch
sudo pacman -S gnome-shell-extension-clipboard-indicator

方式三：手动

git clone https://github.com/Tudmotu/gnome-shell-extension-clipboard-indicator.git \
  ~/.local/share/gnome-shell/extensions/clipboard-indicator@tudmotu.com

gnome-extensions enable clipboard-indicator@tudmotu.com

装完后 Alt+F2 → r → 回车。

配置建议

Extensions 应用 → Clipboard Indicator → 设置
Cache Size → 50~100
开启 Paste on selection
快捷键绑到 Super+Shift+V

	Clipboard Indicator	GPaste	CopyQ
原生 GNOME 集成	✅	❌	❌
响应速度	即时	有延迟	有延迟
数据不出机器	✅	✅	❌（可能写磁盘）
隐私模式	✅	❌	❌
图片支持	✅	❌	✅
额外进程	无	有	有

总结

Clipboard Indicator 不是功能最多的剪贴板管理器，但它是最「GNOME」的 — 原生集成、零延迟响应、数据不出机器。

装了就忘不掉，GNOME 桌面必装。

为什么你输入的链接从「幽香.jpg」变成了「%E7...」

Nywerya's blog — Wed, 03 Jun 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/url-encoding-chinese-links/

为什么你输入的链接从「幽香.jpg」变成了「%E7...」

你有没有见过这种场景

你往 Markdown 里插一张图片：

![幽香](https://cdn.example.com/Obsidian/私人/绘画/幽香.jpg)

写完还挺满意——路径清晰，中文文件名一目了然。Ctrl+C 复制链接，贴到地址栏，回车——图片正常显示。一切正常。

然后你 curl 一下：

curl -I "https://cdn.example.com/Obsidian/私人/绘画/幽香.jpg"

返回 400 Bad Request。

过了几天，你在 Obsidian 里把同一个文件拖进编辑器，发现它自动变成了：

https://cdn.example.com/Obsidian/%E7%A7%81%E4%BA%BA/%E7%BB%98%E7%94%BB/%E5%B9%BD%E9%A6%99.jpg

你盯着这串乱码——不对，这是有规律的，看起来像是某种编码。

没错。这就是 URL 编码。

你每天在互联网上看到的每一个链接，只要包含非英文内容，背后都在经历同样的变形。只是浏览器帮你遮住了——它把乱码藏了起来，让你以为中文链接"本来就能用"。

URL 为什么不能直接写中文

回到 1994 年。

那年 HTTP 1.0 还没正式发布，互联网上跑的链接长这样：

http://example.com/index.html
http://example.com/search?q=hello

全是 ASCII。因为 RFC 1738（URL 规范）明确规定：URL 只能包含 ASCII 可打印字符。理由很朴素——当时互联网上的服务器和路由器五花八门，谁知道某个中间设备收到非 ASCII 字节会怎么处理？

于是得出一条铁律：

URL 里不能有非 ASCII 字符。要传？先编码。

这就是 URL 编码存在的唯一原因。

你说「浏览器不是能显示中文吗？」——那是在地址栏里。浏览器对用户友好，会自动把中文解码显示。但背后的 HTTP 请求，永远、必须、只能是 ASCII。你粘贴到地址栏看到的中文，发出去那一瞬间已经被浏览器偷偷编码了。

不信你打开 F12 → Network，随便点一个中文路径的请求，看 Request URL——全是 %XX。

怎么变的：三句话

编码规则本身不复杂：

把中文字符转成 UTF-8 字节。比如「私」= E7 A7 81（3 字节）
每个字节前面加个 %，写成十六进制 → %E7 %A7 %81
英文字母和数字保持原样，因为 ASCII 安全

以「幽香.jpg」为例：

幽 → UTF-8: E5 B9 BD → %E5%B9%BD
香 → UTF-8: E9 A6 99 → %E9%A6%99
.  → ASCII:  2E       → .（保持）
j  → ASCII:  6A       → j
p  → ASCII:  70       → p
g  → ASCII:  67       → g

结果：「幽香.jpg」→ %E5%B9%BD%E9%A6%99.jpg

同理，「私人」→ %E7%A7%81%E4%BA%BA

脑子里过一遍：UTF-8 里一个 CJK 汉字占 3 字节，所以每个汉字变成 3 组 %XX。

各种场景实测

同一个中文链接，不同地方的表现：

场景	看到的	实际发出的
浏览器地址栏	`私人/绘画/幽香.jpg`	`%E7%A7%81%E4%BA%BA/...`
Markdown 渲染	`私人/绘画/幽香.jpg`	同上，浏览器自动编码
curl (bash)	—	取决于有没有引号，可能炸
wget	—	`400 Bad Request`
Nginx access log	`%E7%A7%81...`	原始编码后请求

想安全地在命令行用中文 URL：

# 错误：shell 可能把中文吞了
curl https://cdn.example.com/Obsidian/私人/绘画/幽香.jpg

# 正确：手动编码
curl "https://cdn.example.com/Obsidian/$(python3 -c "import urllib.parse; print(urllib.parse.quote('私人/绘画/幽香.jpg'))")"

也可以现找一个在线 URL encoder，输入中文得到 %XX 版本。

为什么有的链接中文没问题

现代规范（RFC 3986 + WHATWG URL Standard）放宽了限制——URL 可以包含 Unicode，但浏览器必须内部编码后再发。所以：

浏览器里的链接：大概率没问题，浏览器帮你兜底
微信/QQ 里点的链接：可能没问题，客户端会编码
curl 里的链接：看 shell 和 curl 版本，有时候行有时候炸
nginx rewrite 规则：必须写正则匹配 %XX，不能直接匹配中文

所以是「看你运气」。靠谱做法是自己编码一步到位。

有没有办法不编码直接传中文

有一个提案叫 IRI（Internationalized Resource Identifier，RFC 3987），允许 URL 直接包含 Unicode。现代浏览器和大部分 Web 框架都支持 IRI。

实际效果：

你在地址栏输入 https://网站/中文路径 ← 浏览器支持 IRI 输入
但 HTTP 请求头里还是 https://%E7%BD%91%E7%AB%99/...
所以底层还是编码的

IRI 只是在用户层面让你可以看中文，传输层从未改变。

操作建议

场景	建议
手写 HTML/Markdown	能编码就编码，文件名尽量用英文
配 Nginx location	用 `%XX`，别写中文
bash 脚本	用 Python `urllib.parse.quote()` 编码
图床 CDN	Syncthing 同步到 VPS 时文件名是中文没问题，但公开链接里建议统一编码
写文章引用 CDN 图片	把图片路径跑一遍 encodeURIComponent，粘贴编码后的

我的自建图床 cdn.example.com 上两种链接都能访问——Nginx 收到的都是 %XX 格式，不存在不兼容。区别只在于你肉眼想读中文还是读编码。

最后

URL 编码这件事，说到底是互联网在 30 年前留下的疤痕。

当年那群工程师觉得「ASCII 够用了」，没想过有一天中国人要在互联网上写汉字。等到发现不够用了，只能在上面糊一层编码层——用户看到中文，传输层传 ASCII，来回翻译，谁都不爽但谁也没法推到重来。

你现在看到的每一个 %E7%A7%81，都在替 1994 年的设计决策还债。

自建博客 SEO 实战：不提废话，做完就有效

Nywerya's blog — Tue, 02 Jun 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/self-hosted-blog-seo-guide/

自建博客 SEO 实战：不提废话，做完就有效

适用：Astro / Hexo / Hugo / VitePress 等静态博客，自建域名。

1. 技术基建（一次配好）

1.1 Sitemap

# Astro
pnpm add @astrojs/sitemap

// astro.config.mjs
import sitemap from '@astrojs/sitemap';
export default { integrations: [sitemap()] };

构建后会生成 sitemap-index.xml。

1.2 robots.txt

放入 public/robots.txt：

User-agent: *
Allow: /
Sitemap: https://你的域名/sitemap-index.xml

1.3 文章 Frontmatter 必填项

每篇不缺不漏：

title: 含关键词的标题
description: 150 字内摘要
pubDate: 2026-06-02
image: https://你的图床域名/封面图.png
draft: false
tags:
  - 关键词1
  - 关键词2

1.4 图片优化

用 WebP / AVIF（PNG 太大）
标签写 width height（防 CLS）
封面图放 CDN / 图床，不存 Git 仓库

2. Google Search Console（必做）

打开 search.google.com/search-console
添加资源 → 网址前缀 → 填 https://你的域名
验证（HTML 文件上传最简单：下载 .html 放到 public/，部署即可）
左侧菜单 → 站点地图 → 提交 sitemap-index.xml
网址检查 → 逐个输入你的文章 URL → 请求编入索引

每发一篇新文章，第 5 步重复一次。

3. 内容 Checklist（每篇对照）

项	说明
标题含关键词	搜的人打什么，标题就含什么
URL 语义化	`/blog/deploy-waline` 不是 `/blog/post-3`
内链 2+	每篇链到两篇旧文
H2/H3 含关键词变体	不只是「问题」，而是「搜索权重低怎么办」
首段 100 字摘要	Google 展示在搜索结果里
封面图 1000×600	Open Graph 分享时的社交卡片

4. 站外引流（按优先级）

GitHub：README / 项目主页放博客链接
技术社区：V2EX、掘金发帖时引用
社交媒体：Twitter / 朋友圈转发

5. 检查清单（每次写完文章）

title description pubDate image 不缺
一张封面图，CDN URL 可访问
内链 ≥ 2 篇旧文
URL 可读
部署后去 Search Console 手动提交 URL
Sitemap 状态正常

Linux包管理升级 - 终极指令大全(2026-05)

Nywerya's blog — Sun, 31 May 2026 16:48:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/linux-package-upgrade/

Linux 包管理升级

升级系统内所有已安装软件包，按发行版和包管理器分类。

Debian / Ubuntu (apt)

# 更新软件包列表
sudo apt update

# 升级已安装软件包至最新稳定版本
sudo apt upgrade

# 完整升级：处理包依赖变更和替换
sudo apt full-upgrade

# 清理不再需要的依赖包
sudo apt autoremove

RHEL / CentOS 7 (yum)

# 检查可用更新
sudo yum check-update

# 升级所有已安装软件包
sudo yum update

RHEL / CentOS 8+ / Fedora (dnf)

# 检查可用更新
sudo dnf check-update

# 升级所有已安装软件包
sudo dnf upgrade

# 清理缓存
sudo dnf clean all

Arch Linux (pacman)

# 同步软件包数据库并升级所有已安装软件包
sudo pacman -Syu

# 清理包缓存（保留最近 3 个版本）
sudo paccache -r

OpenSUSE (zypper)

# 更新软件源索引
sudo zypper refresh

# 升级所有已安装软件包
sudo zypper update

Gentoo (emerge)

# 同步 Portage 树并更新整个系统
sudo emerge --sync && sudo emerge --update --deep --newuse @world

# 清理不再需要的依赖
sudo emerge --depclean

Alpine (apk)

# 更新索引并升级所有包
sudo apk update && sudo apk upgrade

Snap（跨发行版）

# 刷新所有已安装 snap 包
sudo snap refresh

# 查看待升级的 snap 列表
sudo snap refresh --list

Flatpak（跨发行版）

# 升级所有已安装 flatpak 应用和运行时
flatpak update

# 清理不再需要的运行时
flatpak uninstall --unused

NixOS (nix)

# 重建系统并升级所有包（切换至新世代）
sudo nixos-rebuild switch --upgrade

# 仅构建不切换（测试用）
sudo nixos-rebuild build --upgrade

# 清理旧世代和包缓存
sudo nix-collect-garbage -d

Void Linux (xbps)

# 同步仓库索引
sudo xbps-install -S

# 升级所有包
sudo xbps-install -u xbps && sudo xbps-install -Su

# 清理旧包缓存
sudo xbps-remove -Oo

升级后操作

# 检查是否需要重启（内核/ glibc / systemd 更新后）
sudo needrestart

# Debian/Ubuntu: 清理旧内核
sudo apt autoremove --purge

# 查看残留配置文件（dpkg 系）
dpkg -l | grep '^rc'

# 对比 .pacnew 配置文件（Arch 系）
sudo pacdiff

通用工具 (topgrade)

# 跨包管理器一键升级所有软件
topgrade

注意：生产环境升级前建议先在测试环境验证，并做好系统备份。

让 Ubuntu 用上官方最新版：跳过「中间商」直达上游

Nywerya's blog — Sun, 31 May 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/bypass-ubuntu-repo-use-official/

让 Ubuntu 用上官方最新版：跳过「中间商」直达上游

你有没有过这种经历——apt install 一个包，装完之后一查版本号，发现比 GitHub 上的 Release 落后了整整一个大版本？

这不是你的问题，是 Ubuntu 的「老派哲学」在作祟。

为什么 Ubuntu 仓库总是慢半拍

Ubuntu（尤其是 LTS 版本）的核心承诺是稳如老狗。发行版发布之后，大多数软件的版本号就被钉死了——维护者只往回移植安全补丁，不给你升大版本。

这套逻辑在服务器上很合理：你不想半夜被一个上游更新炸醒。但当你真的需要某个软件的最新特性（比如 Nginx 刚修了个 9.2 分的 CVE），或者单纯不想用三年前的版本——你就得绕过 Ubuntu，直接找上游。

三步切到官方源

核心思路很简单：把软件作者维护的 apt 仓库加进来，然后告诉 apt "这个源比 Ubuntu 的更优先"。

1. 加密钥，证明你认识这个源

curl -fsSL <官方GPG_URL> | sudo gpg -dearmor -o /usr/share/keyrings/<name>-archive-keyring.gpg

没有 GPG 密钥，apt 不认这个源。密钥文件统一放进 /usr/share/keyrings/，比 /etc/apt/trusted.gpg.d/ 更安全。

2. 加源，告诉 apt 这个仓库在哪

echo "deb [signed-by=/usr/share/keyrings/<name>-archive-keyring.gpg] <官方镜像URL> $(lsb_release -cs) <组件>" | sudo tee /etc/apt/sources.list.d/<name>.list

注意 signed-by= 这个参数——它把这个源锁定到你刚导入的密钥上，别的源就算碰巧同域名也碰不了你。

3. 设优先级，明确表态"我要上游"

printf 'Package: *\nPin: origin <域名>\nPin-Priority: 900\n' | sudo tee /etc/apt/preferences.d/<name>

这就是 apt pinning。通俗解释就是给 apt 排座次：

900 分：apt 会优先选这个源的版本，即使 Ubuntu 官方源有同名包
默认 500 分：两个源都有的话，版本号高的赢
-1 分：死也不装

实战：给 Nginx 装最新版

最近 Nginx 爆了两个有意思的 CVE（CVE-2026-42945 和 CVE-2026-9256），都是 rewrite 模块的堆溢出，一个活了 18 年没被发现，CVSS 双双 9.2 分。Ubuntu 仓库还在 1.24.0，修复版是 1.30.2——这中间差了 6 个大版本。

直接上官方源：

# 加密钥
curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg -dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

# 加源
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://nginx.org/packages/ubuntu/ $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

# 设优先级
printf 'Package: *\nPin: origin nginx.org\nPin-Priority: 900\n' | sudo tee /etc/apt/preferences.d/nginx

# 安装
sudo apt update && sudo apt install nginx

# 验证
nginx -v
# nginx version: nginx/1.31.1

警告：走这条路之前你最好知道

绕开 Ubuntu 维护的包不是没代价的：

风险	说明
无人兜底	不再享受 Ubuntu 安全团队的补丁支持——上游修了你知道，上游没修你只能盯着
依赖地狱	新版本可能依赖更高版本的库，而这些库 Ubuntu 仓库可能没有。装不上就挠头
升级猝死	官方源推一个大版本号更新的时候，配置文件可能不兼容（尤其是 nginx 这种）
无人售后	出问题去 GitHub Issue 对线，没人替你 debug
卸载不易	想退回 Ubuntu 源版本，得先 `ppa-purge` 或手动降级，不是一行命令的事

简单给自己打三个问号再动手：

我真的需要那个新版本的特性吗，还是单纯想「最新」？
这个服务崩了，我能兜得住吗？
我有测试环境可以先试试吗？

如果三条都是「是」——那就放心切。生产环境跑的好好的东西，别动。

Pin-Priority 速查

值	效果
1000+	命令降级——「我要这个版本，管你是升是降」
990	允许降级——「可以往回走」
500-900	优先于同版本号的 Ubuntu 源——「大家都是 1.24，但我选你」
1-499	备胎——「别人都没了才找你」
-1	永不安装——「别再出现了」

收尾

绕开 Ubuntu 仓库有点像从官方直营店买东西——快、新，但没有经销商给你兜底。对于面向公网的服务（比如反代），装最新版反而是件好事：至少 CVE 修得快，不用靠 WAF 硬扛。

一句话总结：知道自己在干什么，就别让中间商赚差价。

部署 Waline 评论系统到自己的服务器完全指南 (保姆级教程 2026)

Nywerya's blog — Sun, 31 May 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/deploy-waline-self-host/

部署 Waline 评论系统到自己的服务器完全指南 (保姆级教程 2026)

简介

Waline 是一个自托管的静态博客评论系统。基于 Node.js，内置管理后台，数据存 SQLite —— 意味着不需要单独装数据库，一个 Docker 容器就跑了。前端是 Web Component（Vue），原生支持暗黑模式、浏览量统计、表情包、Markdown 渲染、数学公式。

这篇教程假设你有一台服务器和一个域名，带你从零把 Waline 跑起来，每一步都有解释。

为什么选 Waline 而不是 Twikoo

对比	Waline	Twikoo
数据库	SQLite（无需额外容器）	MongoDB（必须）
管理后台	内置 `/ui`，注册即用	访问 `/#/login` 设置密码
垃圾过滤	Akismet + IP 频率 + 关键词 + 相似度检测	仅 IP 频率限制
浏览量统计	内置，一行配置	不支持
前端框架	Web Component（Vue）	传统 JS
暗黑模式	`dark: 'auto'` 自适应	需手动适配
登录方式	注册 + GitHub OAuth	仅密码
镜像体积	~150MB（含 SQLite）	需额外 MongoDB 镜像

结论：新项目直接用 Waline，更轻量、功能更全、部署更简单。

第一步：准备工作

你需要这些

东西	说明
一台服务器	1c1g 足够。能 SSH 上去、能装 Docker
一个域名	前端 HTTPS 页面无法请求 HTTP 后端，所以必须有域名配 SSL
一个子域名	给 Waline 专用，比如 `comment.你的域名.com`
15 分钟	从零到评论可用

没有域名怎么办

如果你还没有域名，先去任意域名注册商买一个（Namesilo / Cloudflare / 阿里云都行）。最便宜的 .xyz 一年几块钱。

买完后，在你的 DNS 管理页面添加一条 A 记录，把子域名指向服务器 IP：

类型: A
主机记录: comment      （表示 comment.你的域名.com）
记录值:   123.456.789.0   （你的服务器公网 IP）
TTL:      600

DNS 生效可能需要几分钟。验证一下：

# 在服务器上执行，看子域名是否解析到你的服务器 IP
nslookup comment.example.com

第二步：安装 Docker

如果你的服务器还没装 Docker，先装上。

# 官方一键安装脚本
curl -fsSL https://get.docker.com | sudo sh

# 把当前用户加入 docker 组，以后不用每次加 sudo
sudo usermod -aG docker $USER

# 退出 SSH 重新登录，让用户组生效
exit

重新登录后验证：

docker -version
# 输出类似: Docker version 27.x.x, build ...

docker run -rm hello-world
# 输出 Hello from Docker! 表示 Docker 正常运行

如果 docker pull 特别慢或被墙，参考文末「常见问题」配镜像加速。

第三步：生成配置值

部署 Waline 前，先把要填的值准备好。以下 5 个值需要你替换成自己的：

3.1 JWT_TOKEN —— 管理员密钥

这是 Waline 内部用来签发登录凭证的密钥，必须设，必须保密。

# 在服务器上执行，生成一个随机字符串
openssl rand -hex 32

输出类似 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6e1f2a3b4c5d6。把这个字符串记下来，后面要用。

不要用你别的密码，用 openssl rand 生成的随机值。

3.2 SITE_NAME —— 网站名称

随便写，会显示在管理后台和邮件通知里。比如「XX 的博客」。

3.3 SITE_URL —— 博客地址

你的博客完整地址，带上 https://。比如 https://blog.example.com。

Waline 用这个来判断哪些请求是合法的（CORS 白名单）。

3.4 SECURE_DOMAINS —— 安全域名

你的域名，不带 https://。比如 blog.example.com。

这是评论框允许嵌入的域名白名单。如果你有多个域名（比如 example.com 和 www.example.com），用逗号分隔：example.com,www.example.com。

3.5 AUTHOR_EMAIL —— 你的邮箱

收到新评论时会往这个邮箱发通知（需要配 SMTP，见第五步）。

填完后的参考

假设你的域名是 blog.example.com，子域名打算用 comment.example.com：

变量	值
`JWT_TOKEN`	`a1b2c3d4...`（openssl rand 那串）
`SITE_NAME`	`我的博客`
`SITE_URL`	`https://blog.example.com`
`SECURE_DOMAINS`	`blog.example.com`
`AUTHOR_EMAIL`	`user@example.com`

第四步：部署 Waline 后端

终于要开始部署了。以下操作全部在服务器上执行。

4.1 拉取镜像

docker pull lizheming/waline:latest

镜像大约 150MB，半分钟到一分钟能拉完。

4.1.5 安装 docker-compose（可选，推荐）

之后用 Compose 管理容器比手敲 docker run 方便得多，建议先装上：

sudo apt install -y docker-compose

如果你的 Docker 版本 ≥ 20.10，自带 docker compose 插件（注意是空格不是连字符），那么下面的 docker-compose（有连字符）命令要替换成 docker compose（空格）。版本查看：docker -version

4.2 创建数据目录

Waline 的评论数据存在 SQLite 文件里，这个文件需要挂载到宿主机，否则删容器数据就没了。

mkdir -p /opt/waline/data

/opt/waline/data 是约定俗成的路径，你想放别的地方也行，但后面命令里的路径要跟着改。

4.3 启动容器

把 3.1~3.5 准备好的值填进去，执行：

# 替换以下 5 个值:
#   JWT_TOKEN:      openssl rand -hex 32 生成
#   SITE_NAME:      你的网站名称（含 & 等特殊字符需加引号，如 "Code & Flower"）
#   SITE_URL:       你的博客域名，带 https://
#   SECURE_DOMAINS: 你的域名，不带 https://
#   AUTHOR_EMAIL:   你的邮箱

docker run -d \
  -name waline \
  -restart=unless-stopped \
  -p 127.0.0.1:8360:8360 \
  -v /opt/waline/data:/app/data \
  -e TZ=Asia/Shanghai \
  -e SQLITE_PATH=/app/data \
  -e JWT_TOKEN=a1b2c3d4... \
  -e "SITE_NAME=我的博客" \
  -e SITE_URL=https://blog.example.com \
  -e SECURE_DOMAINS=blog.example.com \
  -e AUTHOR_EMAIL=user@example.com \
  lizheming/waline:latest

每个参数的含义：

参数	作用
`-d`	后台运行
`-name waline`	给容器取名，方便后续操作
`-restart=unless-stopped`	服务器重启后自动启动容器
`-p 127.0.0.1:8360:8360`	只监听本机 8360 端口（不暴露公网，安全）
`-v /opt/waline/data:/app/data`	把宿主机目录挂载进容器，数据持久化
`-e SQLITE_PATH=/app/data`	告诉 Waline SQLite 文件存哪
`-e JWT_TOKEN=...`	管理员登录密钥
`-e SITE_NAME/URL/DOMAINS`	站点信息
`-e AUTHOR_EMAIL`	博主邮箱

关键提示：

bash 续行符 \ 必须是该行最后一个字符，后面不能跟任何东西（包括空格和 # 注释），否则续行会断裂。

如果 SITE_NAME 含 & 等特殊字符，要用双引号包住整个 -e "SITE_NAME=xxx"，否则 bash 会把 & 解释为后台运行符。

4.4 验证容器状态

docker ps | grep waline

看到 Up 字样说明容器在运行：

abc123def456   lizheming/waline:latest   ...   Up 10 seconds   127.0.0.1:8360->8360/tcp   waline

也可以看日志确认有没有报错：

docker logs waline -tail 20

正常的话最后一行类似 ThinkJS 3.x is running at http://127.0.0.1:8360。

4.5 使用 Docker Compose（可选且推荐，在后面操作成功之后回来把配置写进文件里，再启动就不用用一大串命令）

用 Compose 管理比手敲 docker run 更方便，配置一目了然。

新建 docker-compose.yml：

mkdir -p /opt/waline && cd /opt/waline

# docker-compose.yml
version: '3'
services:
  waline:
    container_name: waline
    image: lizheming/waline:latest
    restart: always
    ports:
      - 127.0.0.1:8360:8360
    volumes:
      - ./data:/app/data
    environment:
      TZ: Asia/Shanghai
      SQLITE_PATH: /app/data
      JWT_TOKEN: a1b2c3d4...              # ← 替换
      SITE_NAME: "我的博客"                # ← 替换：含特殊字符需引号
      SITE_URL: https://blog.example.com   # ← 替换
      SECURE_DOMAINS: blog.example.com     # ← 替换
      AUTHOR_EMAIL: user@example.com       # ← 替换
      IPQPS: 5
      AKISMET_KEY: "false"

启动：

# 重启服务
docker stop waline && docker rm waline
docker-compose up -d
docker ps | grep waline

后续改配置也是编辑 docker-compose.yml 然后 docker-compose up -d 即可。

第五步：Nginx 反代 + HTTPS

Waline 只监听了 127.0.0.1:8360，外部访问不到。需要用 Nginx 反代到公网，并配上 HTTPS。

用 Certbot 自动化处理证书 —— 比手动配 acme.sh 简单得多，一条命令就能搞定申请 + 配置 + 自动续期。

5.1 安装 Nginx 和 Certbot

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

5.2 创建临时 HTTP 站点

Certbot 需要通过 HTTP（80 端口）验证域名所有权，所以先建一个 HTTP-only 的 Nginx 站点。替换 server_name 为你的子域名：

sudo tee /etc/nginx/sites-available/waline <<'EOF'
server {
    listen 80;
    server_name comment.example.com;                       # ← 替换：你的子域名

    location / {
        proxy_pass http://127.0.0.1:8360;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header REMOTE-HOST $remote_addr;
    }
}
EOF

启用站点并重载 Nginx：

sudo ln -sf /etc/nginx/sites-available/waline /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

5.3 Certbot 自动获取 SSL 证书

替换域名为你的子域名，然后执行：

sudo certbot -nginx -d comment.example.com

Certbot 交互流程：

输入邮箱 — 用于证书到期提醒（填你的真实邮箱）
同意服务条款 — 输入 Y
是否接收推广邮件 — 输入 N（看你自己）
HTTP 是否自动跳转 HTTPS — 选 2 (Redirect)

执行完后 certbot 自动做了三件事：

申请 Let's Encrypt SSL 证书
把 Nginx 配置改成 HTTPS + 证书路径
加了 HTTP→HTTPS 自动跳转

证书有效期 90 天，certbot 安装时会自动注册 systemd timer，到期前自动续期。手动检查续期状态：sudo certbot renew -dry-run

5.4 验证

curl https://comment.example.com

应该返回一段 JSON：

{"name":"Waline","version":"x.x.x",...}

看到这个 JSON 说明后端已经通过 HTTPS 正常提供服了。

第六步：注册管理员

这一步必须立刻做，免得被别人抢注。

浏览器打开：

https://comment.example.com/ui/register

输入你的邮箱和密码，点击注册。第一个注册的用户自动成为管理员。

注册后就可以登录管理后台了：

https://comment.example.com/ui

管理后台长这样：

左侧是评论列表，可以审核、回复、删除、标星
右上角可以配置站点信息、导入导出数据
支持多用户管理

6.1 服务器目录结构

部署完成后，服务器上的文件布局：

/opt/waline/
├── docker-compose.yml         # 容器配置（如果用 Compose）
└── data/
    └── waline.sqlite           # 评论数据（挂了 volume，删容器不丢）

/etc/nginx/sites-available/waline   # Nginx 站点配置
/etc/nginx/sites-enabled/waline     # 已启用的 symlink

如果用 docker run 而非 Compose，则没有 docker-compose.yml，容器直接通过 docker run 命令管理。

第七步：前端接入

现在后端已经跑起来了，最后一步是把评论框嵌入你的博客页面。

7.1 基础接入

在你想显示评论框的位置（通常是文章页底部）加入以下代码：

<!- 评论框会渲染到这个 div 里 ->
<div id="waline"></div>

<script type="module">
  import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.mjs';

  init({
    el: '#waline',                                 // 评论框要挂载的 DOM 元素
    serverURL: 'https://comment.example.com',       // ← 替换：你的 Waline 后端地址
    dark: 'auto',                                   // 自动跟随系统暗黑模式
    lang: 'zh-CN',                                  // 界面语言
    wordLimit: 500,                                 // 评论字数上限
    pageview: true,                                 // 开启文章浏览量统计
    emoji: [
      'https://unpkg.com/@waline/emojis@1.2.0/qq',   // QQ 表情包
      'https://unpkg.com/@waline/emojis@1.2.0/tieba', // 贴吧表情包
    ],
  });
</script>

init() 返回一个 Waline 实例，可以调用 .update() 更新配置，或 .destroy() 销毁。

7.2 浏览量统计（可选）

如果你想要文章阅读计数，在页面中放一个元素，然后开启 pageview: true：

<!- data-path 填当前页面的路径，用于区分不同文章 ->
阅读量：<span class="waline-pageview-count" data-path="/posts/hello-world"></span> 次

Waline 会自动查找页面上所有 .waline-pageview-count 元素并填入计数。

7.3 常见博客框架的接入方式

不同框架的接入位置略有不同：

框架	在哪加代码
Hugo	`layouts/_default/single.html` 或主题的评论区 partial
Hexo	主题的 `layout/_partial/comments.ejs` 或文章模板
Jekyll	`_layouts/post.html`
VuePress	`.vuepress/config.js` 的 `plugins.comment` 配置
纯 HTML	每篇文章底部直接贴

各种框架的详细配置参考 Waline 官方文档 - 客户端接入。

7.4 验收

部署完前端后，打开你的博客，进入一篇文章，拉到最底：

能看到评论输入框 ✓
输入昵称、邮箱、内容，点发送 ✓
评论成功出现在下方 ✓
登录管理后台能看到这条评论 ✓

恭喜，Waline 已经完整跑起来了。

第八步：邮件通知（可选但建议配）

不配邮件的话，有人评论你不知道。配了 SMTP 后，新评论会自动发邮件通知你。

QQ 邮箱配置示例

登录 QQ 邮箱 → 设置 → 账户 → POP3/IMAP/SMTP 服务
开启「SMTP 服务」，按提示发送短信验证
获得一个 16 位的授权码（不是 QQ 密码！）
把这个授权码填入 SMTP_PASS

添加以下环境变量（如果用的 docker run，加 -e；如果用 Compose，加在 environment 下）：

-e SMTP_SERVICE=QQ \
-e SMTP_USER=你的QQ号@qq.com \
-e SMTP_PASS=授权码 \
-e SENDER_NAME=Waline通知 \

重启容器生效：

docker restart waline

163 邮箱同理，去邮箱设置里开 SMTP 拿授权码，SMTP_SERVICE 填 163。

日常维护

升级 Waline

# Docker Compose 方式
cd /opt/waline
docker compose pull        # 拉最新镜像
docker compose up -d       # 重建容器

# docker run 方式
docker pull lizheming/waline:latest
docker stop waline && docker rm waline
# 重新执行第四步的 docker run 命令

数据在挂载目录里，删容器不会丢。

备份

# SQLite 数据就是一个文件（或几个），直接复制目录
cp -r /opt/waline/data /opt/backup/waline-$(date +%F)

# 建议加个 crontab 每天自动备份
# 0 3 * * * cp -r /opt/waline/data /opt/backup/waline-$(date +\%F)

恢复

# 把备份目录覆盖回数据目录，重启容器即可
cp -r /opt/backup/waline-2026-01-01 /opt/waline/data
docker restart waline

查看日志

docker logs waline -tail 50       # 最近 50 行
docker logs waline -f              # 实时跟踪（Ctrl+C 退出）

进阶：邮箱提醒失败排查

如果你配了 SMTP 但收不到通知邮件：

# 进入容器内部，手动测试邮件发送
docker exec -it waline sh
# 进容器后用 curl 测试发信（Waline 内部 ThinkJS 框架自带测试端点）
curl -X POST http://127.0.0.1:8360/comment \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"test","comment":"测试评论"}'

收到评论后，看 Waline 日志有没有 SMTP 相关报错：

docker logs waline | grep -i smtp

常见原因：

SMTP_PASS 填了邮箱密码而不是授权码（QQ/163 必须用授权码）
SMTP 端口不对（QQ 是 465，163 也是 465，Gmail 是 587）
服务器防火墙屏蔽了 SMTP 端口（出站一般不拦，但如果拦了加白名单）

实战踩坑记录

以下问题来自本次部署的真实踩坑，建议先过一遍。

踩坑 1：bash 命令 `\` 后面不能跟注释

# ❌ 错误：注释会让续行断裂，docker 只执行了第一行
docker run -d \
  -name waline \
  -e SITE_NAME=xxx \   # ← 这个注释会破坏续行

# ✓ 正确：注释单独写，\ 必须是行末最后一个字符
#   以下是替换说明:
#     SITE_NAME: 你的网站名称
docker run -d \
  -name waline \
  -e SITE_NAME=xxx

踩坑 2：SITE_NAME 含 `&` 必须加引号

SITE_NAME=Code & Flower 在 bash 里 & 会被解释为「放后台运行」，命令就断了。

# ❌ 错误
-e SITE_NAME=Code & Flower

# ✓ 正确：双引号包住整个 key=value
-e "SITE_NAME=Code & Flower"

YAML（Compose）里同样需要：

# ✓ 正确
SITE_NAME: "Code & Flower"

踩坑 3：SECURE_DOMAINS 必须包含管理后台域名

SECURE_DOMAINS 控制的是 Waline API 允许哪些域名跨域访问。管理后台也在 comment.xxx.com 上，不加上去的话注册/登录 API 返回 403。

# ❌ 错误：只写了博客域名
-e SECURE_DOMAINS=blog.example.com

# ✓ 正确：博客域名 + 管理后台域名，逗号分隔
-e SECURE_DOMAINS=blog.example.com,comment.example.com

踩坑 4：SQLite 文件需要预初始化

直接删掉 waline.sqlite 后重启容器，Waline 会创建一个 0 字节的空文件，不会自动建表，注册时报 no such table: wl_Users。

解决办法 —— 下载官方预初始化的数据库文件：

# GitHub 直连失败用镜像
wget -O /opt/waline/data/waline.sqlite \
  https://ghproxy.net/https://raw.githubusercontent.com/walinejs/waline/main/assets/waline.sqlite
docker restart waline

如果你已经注册了用户再删数据库，数据会丢失。升级或迁移不要直接删文件，用管理后台的导出/导入功能。

踩坑 5：社交登录（GitHub/QQ）在国内可能 403

Waline 的第三方登录走 oauth.lithub.cc 代理，这个服务在国内访问不稳定，经常返回 403。这不是你配置的问题，是代理服务本身的问题。

用邮箱注册就够了，去 /ui/register 填邮箱和密码。访客评论也可以用昵称 + 邮箱，不需要登录。

账号归属

Waline 跑在你自己的服务器上，所有用户注册的账号、评论数据都存在你的 /opt/waline/data/waline.sqlite 里。账号只在你的网站有效，去别人家用 Waline 的网站需要重新注册——这不是 SaaS 平台。

常见问题

评论一直转圈、发送失败

99% 是 serverURL 填错了或者 HTTPS 证书有问题。

排查步骤：

浏览器 F12 → Console → 看报错信息
如果是 Failed to fetch：检查 serverURL 是否以 https:// 开头
直接浏览器访问 https://你的子域名，看是否返回 JSON
检查证书是否过期：curl -I https://你的子域名

关闭垃圾评论过滤，加快评论速度

设置 AKISMET_KEY=false 关闭 Akismet 检测：

# docker run 方式加这行
-e AKISMET_KEY=false

# 如果已经跑起来了
docker stop waline && docker rm waline
# 重新 docker run 时加上上面的 -e AKISMET_KEY=false

Failed to fetch 错误

POST https://comment.example.com/comment net::ERR_FAILED

原因排查：

Waline 没在运行：docker ps | grep waline
Nginx 没反代对：curl http://127.0.0.1:8360 看看本地能不能访问
HTTPS 证书过期：curl -Iv https://comment.example.com 看证书信息
域名 DNS 没解析：nslookup comment.example.com
防火墙没开放：443 端口要在安全组里放行

管理后台打不开 / 404

确认 URL 路径是 /ui，不是 /ui/（末尾不加斜杠）
首次访问应该去 /ui/register 注册
如果 /ui 返回页面但是空白：检查浏览器是否有广告拦截插件，暂时关掉

Docker pull 太慢或失败

国内服务器拉 Docker 镜像可能会很慢。配镜像加速：

sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

LeanCloud 用户迁移到自建

如果你以前用 LeanCloud 版 Waline，现在想迁移到自建 SQLite：

登录 LeanCloud → 找到 Waline 应用 → 导出数据（JSON 或 CSV）
自建 Waline 跑起来后，在管理后台 /ui 里有「导入」功能
把导出的数据导入即可

升级 @waline/client v2 → v3

@waline/client v3 的初始化方式从 Waline.init() 变成了 init()，API 不兼容。如果你的博客还在用 v2 的 CDN 地址，升级时注意同步改前端代码。

参考

如何部署 Twikoo 评论到自己的服务器 (保姆级教程 2026)

Nywerya's blog — Fri, 29 May 2026 00:00:00 GMT

This rendering was automatically generated by Ryuchan Feed and may have formatting issues. For the best experience, please visit: https://blog.nywerya.xyz/blog/deploy-twikoo-self-host/

如何部署 Twikoo 评论到自己的服务器 (保姆级教程 2026)

简介

Twikoo 是一个自托管的静态博客评论系统，后端用 Node.js，数据库用 MongoDB。前端通过一个 JS 脚本嵌入页面。

需要什么

一台能装 Docker 的服务器（1c1g 够用）
MongoDB（可以同一台服务器上跑，也可以用 MongoDB Atlas 免费版）
一个域名（前端 HTTPS 站点才能正常请求）

部署步骤

1. MongoDB

如果已有 MongoDB 可跳过。没有的话，在服务器上起一个：

# 拉镜像
docker pull mongo:7

# 运行，挂载数据目录
docker run -d -name mongo \
  -v /opt/mongo/data:/data/db \
  -p 127.0.0.1:27017:27017 \
  mongo:7

或者用 MongoDB Atlas 免费云（512MB 够用了），注册后获取连接字符串。

2. 运行 Twikoo

# 拉镜像
docker pull imaegoo/twikoo

# 运行
docker run -d -name twikoo \
  -restart=unless-stopped \
  -e TWIKOO_THROTTLE=1000 \
  -e MONGODB_URI=mongodb://mongo:27017/twikoo \
  -link mongo \
  -p 127.0.0.1:8080:8080 \
  imaegoo/twikoo

如果 MongoDB 在一台机器上且没用 -link，直接用宿主机 IP 或者把 -link 换成 -network host：

# 用宿主机网络（Mongo 也同一台机器）
docker run -d -name twikoo \
  -restart=unless-stopped \
  -network host \
  -e TWIKOO_THROTTLE=1000 \
  -e MONGODB_URI=mongodb://127.0.0.1:27017/twikoo \
  imaegoo/twikoo

用 MongoDB Atlas 的话，MONGODB_URI 换成 Atlas 连接字符串。

3. Nginx 反代

假设你的域名是 comment.example.com：

server {
    listen 443 ssl http2;
    server_name comment.example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# 验证并重载
sudo nginx -t && sudo systemctl reload nginx

4. 前端接入

在博客页面引入 Twikoo JS，挂载到指定 DOM 元素：

<div id="twikoo-comments"></div>

<script src="https://cdn.jsdelivr.net/npm/twikoo@1.6.41/dist/twikoo.all.min.js"></script>
<script>
twikoo.init({
  envId: 'https://comment.example.com',
  el: '#twikoo-comments',
  // 可选：语言、表情CDN、管理员鉴权等
  lang: 'zh-CN',
});
</script>

5. 管理面板

浏览器打开 https://comment.example.com/#/login，第一次会设置管理员密码。之后可以在这里管理评论（审核、删除、回复等）。

常用环境变量

变量	说明	默认值
`TWIKOO_THROTTLE`	同一 IP 评论间隔（毫秒）	60000
`TWIKOO_IP_HEADERS`	获取真实 IP 的请求头，逗号分隔	`x-forwarded-for`
`MONGODB_URI`	MongoDB 连接字符串	—

常见问题

评论发送失败 / 一直转圈 → 检查浏览器控制台，大概率是 HTTPS 证书问题或反代没配 WebSocket 升级头。

管理面板进不去 → 确保 URL 以 /#/login 结尾，域名都能正常访问。

WordPress 能不能用 → 只适合静态博客，WordPress 不需要这个。

备份

# 评论存在 MongoDB 里，备份数据库即可
docker exec mongo mongodump -archive=/tmp/twikoo-$(date +%F).archive
docker cp mongo:/tmp/twikoo-$(date +%F).archive .