业余玩家

Fuwari 主题：添加文章置顶功能

Wed, 08 Oct 2025 21:00:00 GMT

修改工具文件

修改排序逻辑（一）

src/utils/content-utils.ts，首先修改 getRawSortedPosts 函数。该函数被归档页面调用，同样需要加入置顶排序逻辑：

async function getRawSortedPosts() {
    const allBlogPosts = await getCollection("posts", ({ data }) => {
        return import.meta.env.PROD ? data.draft !== true : true;
    });

    const sorted = allBlogPosts.sort((a, b) => {
        // 如果一个是置顶一个不是置顶，置顶的排在前面
        if (a.data.pinned !== b.data.pinned) {
            return a.data.pinned ? -1 : 1;
        }
        // 都是置顶或都不是置顶，按发布日期时间排序（包含小时分钟秒）
        const dateA = new Date(a.data.published);
        const dateB = new Date(b.data.published);
        return dateA > dateB ? -1 : 1;
    });
    return sorted;
}

修改排序逻辑（二）

接着修改 getSortedPosts 函数，该函数被首页和 RSS 等页面调用：

export async function getSortedPosts() {
	const allBlogPosts = await getCollection("posts", ({ data }) => {
		return import.meta.env.PROD ? data.draft !== true : true;
	});
	const sorted = allBlogPosts.sort((a, b) => {
		// 如果一个是置顶一个不是置顶，置顶的排在前面
		if (a.data.pinned !== b.data.pinned) {
			return a.data.pinned ? -1 : 1;
		}
		// 都是置顶或都不是置顶，按发布日期时间排序（包含小时分钟秒）
		const dateA = new Date(a.data.published);
		const dateB = new Date(b.data.published);
		return dateA > dateB ? -1 : 1;
	});

	for (let i = 1; i < sorted.length; i++) {
		sorted[i].data.nextSlug = sorted[i - 1].slug;
		sorted[i].data.nextTitle = sorted[i - 1].data.title;
	}
	for (let i = 0; i < sorted.length - 1; i++) {
		sorted[i].data.prevSlug = sorted[i + 1].slug;
		sorted[i].data.prevTitle = sorted[i + 1].data.title;
	}
	
	return sorted;
}

修改文章配置文件

src/content/config.ts，在 lang 字段后增加 pinned 字段

pinned: z.boolean().optional().default(false),

修改置顶显示标签

src/components/PostCard.astro,此文件需要修改两处。

第一处：添加置顶标签判断

const isPinned = entry.data.pinned === true;

第二处：添加置顶标签显示

{isPinned && (
    <span class="inline-flex items-center mr-2 px-2 py-0.5 text-sm font-medium bg-[oklch(97%_0.1_var(--hue))] dark:bg-[oklch(30%_0.1_var(--hue))] text-[oklch(55%_0.1_var(--hue))] dark:text-[oklch(80%_0.1_var(--hue))] rounded">
        <Icon name="material-symbols:push-pin" class="mr-1 text-base" /> 置顶
    </span>
)}

Linux 网络排查：TIME_WAIT、偶发丢包与 MTU 黑洞的内核调优实战

Sun, 24 May 2026 14:31:19 GMT

线上网络故障最难受的不是宕机——宕机至少能快速定位。真正消耗时间的，是那些"看上去都正常但就是不对劲"的玄学问题：TCP 握手成功但传不动数据、curl 偶发卡 5s 然后突然返回、监控显示 0% 丢包但用户喊延迟飙升。这篇文章把我反复踩过的三类网络坑梳理一下，配上排查命令和内核参数调优。

故事：从一个"假死"的服务说起

某天凌晨告警炸了：一个对外的 HTTP API 网关在持续 5xx，但进程没挂，CPU、内存、磁盘 IO 都健康，业务日志也没有报错堆栈。SSH 上去 curl 127.0.0.1 是好的，从外网请求却几乎全部超时。

第一反应是查连接数：

ss -s

Total: 142
TCP:   65823 (estab 312, closed 65498, orphaned 0, timewait 65497)

Transport Total     IP        IPv6
TCP       325       213       112
UDP       12        8         4

timewait 65497——TIME_WAIT 已经把可用端口塞满了。这就是后面要讲的第一个坑。直观感受一下：

 本地端口范围   32768 ───────────────────────────── 60999
                ┌──────────────────────────────────────┐
 端口占用       │ ████████████████████████████████████ │  ← TIME_WAIT 把池子吃光
                └──────────────────────────────────────┘
                                  │
                                  ▼
                  新连接 connect() → EADDRNOTAVAIL
                  curl / 业务调用看到的就是"超时 / 失败"

:::tip 排查网络问题之前，先做一件事：在脑子里把 OSI 七层从下到上过一遍，每一层问自己"这里能挂吗"。从物理层（网卡 / MTU）到传输层（TCP 状态、端口、conntrack）再到应用层（重试、超时），按层定位比拍脑袋猜要快得多。 :::

坑一：TIME_WAIT 堆积导致服务"假死"

现象

服务进程活着、CPU 不高
本地回环正常，外部请求大量超时或 Connection reset
ss -s 看到 TIME_WAIT 数万甚至几十万
dmesg 里出现 TCP: time wait bucket table overflow 或 kernel: nf_conntrack: table full

原理速记

TCP 主动关闭方在四次挥手后会进入 TIME_WAIT 状态，停留 2 * MSL（Linux 内核里写死了 60 秒，对应 TCP_TIMEWAIT_LEN）：

   主动关闭方                          被动关闭方
   ──────────                          ──────────
  ESTABLISHED                         ESTABLISHED
       │                                   │
       │ ───────── FIN ──────────────▶     │
  FIN_WAIT_1                               │
       │ ◀───────── ACK ──────────────     │ CLOSE_WAIT
  FIN_WAIT_2                               │  (应用还没 close)
       │                                   │
       │ ◀───────── FIN ──────────────     │ LAST_ACK
       │ ───────── ACK ──────────────▶     │
   TIME_WAIT                            CLOSED
       │
       │   2 × MSL = 60s
       │   ↑ 等待两个 MSL，确保：
       │     ① 最后那个 ACK 真的送达
       │     ② 旧连接的迟到报文在网络中自然消亡
       ▼
    CLOSED

这个等待是必要的，目的是：

让网络中迟到的报文有机会被丢弃，避免污染下一个相同四元组的连接
保证被动关闭方收得到最后一个 ACK

正常场景下 TIME_WAIT 完全无害。出问题的是这种模式：本机作为客户端短连接大量主动关闭（典型场景：API 网关回源、PHP-FPM 调外部 HTTP 服务、爬虫）。

每个 TIME_WAIT 占用一个四元组（本地 IP + 本地端口 + 远端 IP + 远端端口）。如果回源目标固定，那相当于本地端口范围被吃光：

sysctl net.ipv4.ip_local_port_range
# net.ipv4.ip_local_port_range = 32768  60999

默认能用的端口只有约 28k 个，对一个高并发回源的网关来说撑不了多久。

排查命令

# 查看各状态连接数
ss -ant | awk 'NR>1 {print $1}' | sort | uniq -c | sort -rn

# 看 TIME_WAIT 都集中在哪个对端（确认是不是单点回源）
ss -ant state time-wait | awk '{print $5}' | cut -d: -f1 | sort | uniq -c | sort -rn | head

# 看本地端口耗尽情况
ss -s
cat /proc/net/sockstat

sockets: used 65800
TCP: inuse 312 orphan 0 tw 65497 alloc 65812 mem 4123

tw 字段就是 TIME_WAIT 总数，alloc 是已分配的 socket 数，逼近 net.ipv4.tcp_max_tw_buckets 时就要警惕了。

调优

把以下参数加到 /etc/sysctl.d/99-network.conf，sysctl -p 生效：

# 扩大本地端口范围
net.ipv4.ip_local_port_range = 1024 65535

# 允许重用 TIME_WAIT 状态的端口给新的出向连接（依赖时间戳）
net.ipv4.tcp_tw_reuse = 1

# TIME_WAIT 桶上限，超过即直接销毁，避免内核打日志
net.ipv4.tcp_max_tw_buckets = 262144

# 时间戳必须打开，tcp_tw_reuse 才有效
net.ipv4.tcp_timestamps = 1

:::warning 不要再用 net.ipv4.tcp_tw_recycle。这个参数从 Linux 4.12 起已经被完全移除——它依赖时间戳做快速回收，在客户端经过 NAT 时会因时间戳乱序丢连接，是经典坑。能调的只有 tcp_tw_reuse。 :::

:::important tcp_tw_reuse 只对**主动发起连接（客户端方向）**有效。监听端口收到的入向 TIME_WAIT 它管不着。如果是服务端 TIME_WAIT 堆积，要解决的是"为什么是服务端主动关闭"——通常是长连接被错误地关掉，或者应用层 keep-alive 没启用。 :::

应用层能做的事：

开启 HTTP keep-alive（连接复用），nginx 上游加 keepalive 256;
用连接池而不是每次新建（Go http.Client 一定要全局复用，Python 用 requests.Session）
协议允许就走长连接（gRPC / WebSocket / 数据库连接池）

坑二：偶发丢包——监控显示 0%，但用户在喊延迟

这是最折磨人的一类问题，因为它不是"完全坏"，是"偶尔坏"。

排查之前先建立一张"包从网线到应用"的全景图，每一层都可能默默丢包，下面的 5 个步骤就是按这张图自底向上走的：

 ┌──────────────────────────────────────────────────────────────┐
 │  应用层                                                       │
 │     ┌──────────────┐                                         │
 │     │  accept() 队列│  ← 第 2 步：ListenOverflows / Backlog drop
 │     └──────┬───────┘                                         │
 ├────────────┼─────────────────────────────────────────────────┤
 │  传输层    │   TCP / UDP                                      │
 │     ┌──────▼───────┐    ┌──────────┐                         │
 │     │ recv buffer  │    │ SYN 队列  │  ← TcpExtListenDrops    │
 │     └──────────────┘    └──────────┘                         │
 ├──────────────────────────────────────────────────────────────┤
 │  网络层 / netfilter                                           │
 │     ┌────────────────────┐                                   │
 │     │ conntrack 表       │  ← 第 3 步：table full → 静默丢包   │
 │     └────────────────────┘                                   │
 │     ┌────────────────────┐                                   │
 │     │ iptables / nftables│  ← DROP / REJECT                  │
 │     └────────────────────┘                                   │
 ├──────────────────────────────────────────────────────────────┤
 │  软中断 (softirq / RPS)                                       │
 │     ┌────────────────────┐                                   │
 │     │ per-CPU backlog    │  ← netdev_max_backlog 满          │
 │     └────────────────────┘                                   │
 ├──────────────────────────────────────────────────────────────┤
 │  网卡驱动                                                     │
 │     ┌────────────────────┐                                   │
 │     │ RX ring buffer     │  ← 第 1 步：rx_dropped / fifo_err  │
 │     └────────────────────┘                                   │
 ├──────────────────────────────────────────────────────────────┤
 │  物理网卡 / 线缆                                              │
 │     ←───────────── 报文从这里进来 ─────────────               │
 └──────────────────────────────────────────────────────────────┘
                                          ↑
                                     抓不到包就上 tcpdump (第 4 步)
                                     还是定位不到就 dropwatch (第 5 步)

第 1 步：先看网卡层有没有丢

# 看接口统计：errors / dropped 是关键
ip -s link show eth0

# 网卡硬件层统计（更细，包含 rx_no_buffer 等）
ethtool -S eth0 | grep -Ei 'drop|err|miss|fifo'

# 看 ring buffer 是否打满
ethtool -g eth0

如果 rx_dropped、rx_fifo_errors、rx_missed_errors 在涨，说明网卡 ring buffer 不够大或者 softirq 处理不过来。前者改 ring buffer：

# 当前可能是 256/256，最大支持看 "Pre-set maximums"
ethtool -G eth0 rx 4096 tx 4096

后者是 CPU/中断的问题：单队列网卡所有中断打到一个 CPU，那个核飙到 100% si（软中断）就开始丢包。检查：

# 看 softirq 是否倾斜
mpstat -P ALL 1

# 看中断在哪个 CPU
cat /proc/interrupts | grep eth0

解决方案：开启 RPS（Receive Packet Steering） 或 RSS（多队列），把软中断分散到多核：

# 把 eth0 的 rx 队列 0 的软中断分散到 CPU 0-7
echo ff > /sys/class/net/eth0/queues/rx-0/rps_cpus

第 2 步：协议栈是不是在丢

# TCP/UDP/IP 层各种异常计数器（强烈推荐）
nstat -az | grep -Ei 'drop|retrans|listen|overflow|prune'

# 老牌工具，等价信息
netstat -s | grep -Ei 'drop|retrans|listen|overflow|prune'

重点看几个字段：

字段	含义
`TcpExtListenOverflows`	accept 队列溢出，应用层 accept 不及时
`TcpExtListenDrops`	SYN 队列或 accept 队列丢 SYN
`TcpExtTCPBacklogDrop`	已建连但 socket 缓冲区满，包被丢
`TcpExtPruneCalled` / `TCPRcvCollapsed`	接收缓冲区不够，触发回收，性能急剧下降
`TcpRetransSegs`	重传段，对照基线看是否飙升
`IpReasmFails`	IP 分片重组失败（提示 MTU 问题，见坑三）

ListenOverflows 涨说明应用 accept 慢了，调大队列：

net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535

应用层也要配套，nginx 的 listen 80 backlog=65535;、Go net.Listen 后的 ListenConfig{KeepAlive}、Java Netty 的 SO_BACKLOG 都要设。

第 3 步：conntrack 表满

这个特别隐蔽，会让数据包"无声"地被丢，应用层完全感知不到：

# 当前 conntrack 数 / 上限
cat /proc/sys/net/netfilter/nf_conntrack_count
cat /proc/sys/net/netfilter/nf_conntrack_max

# dmesg 里搜 "table full"
dmesg | grep -i conntrack

nf_conntrack: table full, dropping packet 出现就说明已经在丢。调大：

net.netfilter.nf_conntrack_max = 1048576
net.netfilter.nf_conntrack_buckets = 262144   # 通常设为 max 的 1/4
net.netfilter.nf_conntrack_tcp_timeout_established = 600

:::caution 如果机器只是单纯做转发或者根本不需要 NAT，可以直接 modprobe -r nf_conntrack 或在 iptables 里给关键链加 NOTRACK，比调大表更治本。但前提是你不用 docker / k8s 默认的 SNAT，否则关掉会炸网络。 :::

第 4 步：抓包确认

到这一步还没结论，就上 tcpdump：

# 抓特定对端的所有包，写到文件方便 Wireshark 分析
tcpdump -i eth0 -nn -s 0 -w /tmp/cap.pcap host 10.0.0.5 and port 443

# 只看 SYN 和 RST，定位握手问题
tcpdump -i eth0 -nn 'tcp[tcpflags] & (tcp-syn|tcp-rst) != 0'

# 实时看重传（粗略）
tcpdump -i eth0 -nn -A 'tcp[13] & 0x04 != 0 or tcp[13] & 0x02 != 0'

Wireshark 里看 tcp.analysis.retransmission、tcp.analysis.duplicate_ack、tcp.analysis.zero_window，比命令行直观得多。

:::tip 线上抓包加 -s 0 -w 必加 host / port 过滤，否则 pcap 文件能在分钟内吃光磁盘。还有个更好的工具是 tcpdump -i eth0 -nn ... | head -1000，限制行数防止刷屏。 :::

第 5 步：内核层面看丢包点

如果以上都没线索，用 dropwatch 直接定位是内核哪一行代码丢的包：

dropwatch -l kas
> start
# ...几秒后
> stop

输出会告诉你 tcp_v4_rcv+0x1b3/0x500 之类的具体函数。对深度排查很有用，但门槛较高，作为最后手段。

坑三：MTU 黑洞——能 ping 通但传文件卡死

这是最玄学的一个。现象典型组合：

ping 对端正常，延迟也不高
curl 拉小页面 200 OK
一旦响应体变大（比如 10KB+）就卡死、超时
SSH 登录能连上，敲命令到一半再回车就没反应了

九成是 MTU 不匹配 + ICMP 被防火墙吞了，也就是教科书上说的 Path MTU Discovery 黑洞。

                  ┌──── 中间链路 MTU = 1400 ────┐
   Client                                          Server
   MTU=1500  ──── 物理网卡 ────  ──── 物理网卡 ──── MTU=1500

   ① 小包 (1200B, DF=1)
      ────●─────────────────────────────●────▶   ✓ 顺利通过

   ② 大包 (1500B, DF=1)
      ────●─────────╳                   ●        ✗ 在中间链路被丢
                    │
                    │  路由器本应回送 ICMP Type 3 Code 4
                    ▼  "Fragmentation Needed, MTU=1400"
                    ╳  被防火墙整段 ban 掉 ICMP → 发送方完全不知情
                          │
                          ▼
                    持续按 1500 重传 → 应用层看到的现象就是
                    "能 ping 通、能建连、一传大包就卡死"

原理

TCP 协商时会基于本地 MTU 算 MSS（MSS = MTU - 40），一张图看清各字段在以太帧里占的位置：

 ┌──── Ethernet 帧 (链路层) ─────────────────────────────────────┐
 │ DMAC 6│ SMAC 6│ Type 2│           Payload ≤ MTU (默认1500)    │
 └───────┴───────┴───────┴───────────────────────────────────────┘
                         │
                         ▼
                ┌──── IP 包  (MTU = 1500) ───────────────────────┐
                │ IP 头 20  │ TCP 头 20 │   TCP 数据 ≤ MSS = 1460 │
                └───────────┴───────────┴─────────────────────────┘
                                         ↑
                          MSS = MTU − IP头(20) − TCP头(20) = 1460
                          IPv6 / TCP 时间戳选项启用时再各扣几字节

当数据包经过中间链路（VPN、隧道、运营商 PPPoE）时，链路 MTU 可能比两端都小。本来应该靠 ICMP Fragmentation Needed (Type 3, Code 4) 通知发送方降低分片大小，但很多防火墙傻乎乎把所有 ICMP 全 ban 了，于是发送方既不知道要分片，又因为 IP 头有 DF 标记不能在中间分片——大包就这样被静默吞掉。

为什么小包没事？因为小包没超过中间最小 MTU，根本走得过去。

排查

最简单的方法：手动试探 PMTU。

# -M do：禁止分片；-s 1472：1472 + 28(ICMP+IP) = 1500 字节
ping -M do -s 1472 target.example.com

# 如果上面失败，逐步减小，直到通过
ping -M do -s 1400 target.example.com
ping -M do -s 1300 target.example.com

找到能通过的最大 -s 值，加 28 就是路径 MTU。

或者用 tracepath，自动探测：

tracepath target.example.com

 1?: [LOCALHOST]                      pmtu 1500
 1:  10.0.0.1                                          0.523ms 
 1:  10.0.0.1                                          0.491ms 
 2:  ...                                               1.234ms pmtu 1400
 3:  target.example.com                                3.456ms reached

pmtu 1400 这一跳就是瓶颈。

抓包视角看就更明显：

tcpdump -i eth0 -nn -vv 'icmp[icmptype] = 3'

看不到 ICMP Type 3 → 中间防火墙吞了 → PMTU 黑洞实锤。

修复

方案 A：调小本机 MTU（兜底，但治标不治本）：

ip link set eth0 mtu 1400

方案 B：在路由表上钉死 MSS（推荐，对特定目标生效）：

# 通过 iptables 在 SYN 上 clamp MSS
iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN \
  -j TCPMSS --clamp-mss-to-pmtu

对 VPN/WireGuard/IPSec 场景几乎是必配。WireGuard 默认 MTU 1420，对端如果走再套一层 GRE 之类还得继续减。

方案 C：开启 TCP MTU Probing，让内核自己探测：

net.ipv4.tcp_mtu_probing = 1
net.ipv4.tcp_base_mss = 1024

tcp_mtu_probing = 1 是"只在检测到黑洞时启用"，比较保守；= 2 是"始终启用"。建议从 1 开始。

:::important 做 Overlay 网络（Docker、k8s CNI、VXLAN、IPIP）时，永远要意识到内层 MTU 会比物理网卡小。VXLAN 头 50 字节，所以物理 MTU 1500 时内层应该是 1450。Flannel、Calico 默认会处理这件事，但自建隧道时常常忘掉。 :::

内核参数调优清单

把上面散落的参数汇总成一份可以直接抄的模板，放在 /etc/sysctl.d/99-network.conf：

# ===== 连接管理 =====
net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_max_tw_buckets = 262144
net.ipv4.tcp_timestamps = 1
net.ipv4.tcp_fin_timeout = 15

# ===== 队列与缓冲区 =====
net.core.somaxconn = 65535
net.core.netdev_max_backlog = 32768
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_syncookies = 1

# ===== 收发缓冲区（按需，大带宽延迟积场景才调） =====
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216

# ===== 拥塞控制 =====
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

# ===== conntrack（NAT / 转发场景）=====
net.netfilter.nf_conntrack_max = 1048576
net.netfilter.nf_conntrack_tcp_timeout_established = 600

# ===== MTU 探测 =====
net.ipv4.tcp_mtu_probing = 1

# ===== Keepalive（让僵尸连接更快被清理）=====
net.ipv4.tcp_keepalive_time = 600
net.ipv4.tcp_keepalive_intvl = 30
net.ipv4.tcp_keepalive_probes = 3

应用：

sysctl -p /etc/sysctl.d/99-network.conf

:::warning 不要照搬。这份参数适合"高并发、对外提供服务的 Linux 主机"。如果你的机器是数据库、做 NAT 网关、还是单纯桌面，每一项都要按场景判断。比如把 rmem_max 调到 16M 在低 BDP（带宽延迟积）链路上反而浪费内存。 :::

常用排查命令速查

按"看哪一层"组织，故障来时按顺序敲：

ip -s link show eth0                   # 接口收发计数、错误统计
ethtool eth0                           # 协商速率、双工
ethtool -S eth0 | grep -i err          # 网卡硬件错误
ethtool -g eth0                        # ring buffer 大小
dmesg -T | tail -50                    # 网卡 reset / 链路抖动

ip route                               # 路由表
ip neigh                               # ARP / NDP 邻居
ping -M do -s 1472 <host>              # PMTU 探测
mtr -rwn <host>                        # 持续 traceroute，看丢包点
tracepath <host>                       # 自动 PMTU 探测

ss -ant                                # 所有 TCP，比 netstat 快得多
ss -anti                               # 加 -i 看每个连接的拥塞窗口、RTT
ss -ltnp                               # 监听端口 + 进程
ss -s                                  # 各状态汇总
nstat -az                              # 协议栈计数器（推荐）
netstat -s                             # 同上，老牌
cat /proc/net/sockstat                 # socket / TIME_WAIT 总览

iptables -L -vn --line-numbers
nft list ruleset
cat /proc/sys/net/netfilter/nf_conntrack_count
conntrack -L                           # 当前所有连接追踪记录

tcpdump -i eth0 -nn -s 0 -w cap.pcap host X
tshark -i eth0 -Y 'tcp.analysis.retransmission'
dropwatch -l kas                       # 内核丢包点定位
bpftrace -e 'kprobe:tcp_drop { @[kstack] = count(); }'

总结

线上网络问题之所以"玄学"，是因为表象（应用层报错）和根因（内核状态、链路 MTU、conntrack 表）之间有好几层间接关系。一旦养成"按层排查"的肌肉记忆，绝大多数所谓诡异问题都会变成可复现、可解释的事故。

收尾建议：

基线监控比事中救火更重要。把 ss -s、nstat、conntrack_count、net_dropped 拉到监控里，比出事后再去看真实数据有价值得多
不要迷信"重启就好了"。能重启好的问题大多是参数 / 资源耗尽问题，下一次它一定会再来
改内核参数前先记下原值。sysctl net.ipv4.tcp_tw_reuse 看到旧值再改，回滚才有依据
应用层和内核层一起调。somaxconn = 65535 但 nginx backlog 默认 511，等于白调

最后一句话：tcp_tw_recycle 永远不要碰，永远。

Claude Code 对接 DeepSeek V4 Pro：完整配置指南

Sat, 23 May 2026 12:49:50 GMT

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，深度集成在终端和 VSCode 中。虽然它默认使用 Anthropic 自家的 Claude 模型，但通过 DeepSeek 提供的 Anthropic 兼容 API，我们可以用 DeepSeek V4 Pro 来驱动 Claude Code，大幅降低成本（约 99%）。

1. Claude Code CLI 对接 DeepSeek V4 Pro

1.1 安装 Claude Code

首先确保安装了 Node.js 18+，然后全局安装 Claude Code：

npm install -g @anthropic-ai/claude-code

验证安装：

claude --version

1.2 配置环境变量

DeepSeek 提供了一个兼容 Anthropic API 的端点 https://api.deepseek.com/anthropic，只需设置几个环境变量即可让 Claude Code 指向 DeepSeek。

在 ~/.zshrc（或 ~/.bashrc）中添加：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="<你的 DeepSeek API Key>"
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_EFFORT_LEVEL="max"

使配置生效：

source ~/.zshrc

1.3 环境变量说明

变量	值	说明
`ANTHROPIC_BASE_URL`	`https://api.deepseek.com/anthropic`	DeepSeek 的 Anthropic 兼容端点
`ANTHROPIC_AUTH_TOKEN`	你的 API Key	在 DeepSeek Platform 获取
`ANTHROPIC_MODEL`	`deepseek-v4-pro[1m]`	主力模型，适合复杂代码分析
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	`deepseek-v4-flash`	轻量模型，适合简单任务
`CLAUDE_CODE_SUBAGENT_MODEL`	`deepseek-v4-flash`	子 Agent 使用 Flash 以节省成本
`CLAUDE_CODE_EFFORT_LEVEL`	`max`	最高努力级别

1.4 模型选择

DeepSeek V4 系列目前提供两个模型：

deepseek-v4-pro[1m]：主力模型，1M 上下文窗口，适合复杂代码分析、大型项目重构、多文件编辑
deepseek-v4-flash：快速轻量模型，适合日常问答、简单代码修改、子 Agent 任务

1.5 启动使用

配置完成后，在项目目录下直接运行：

cd /path/to/your-project
claude

即可进入 Claude Code 交互界面，底层已经切换为 DeepSeek V4 Pro。

2. VSCode 插件对接 DeepSeek V4 Pro

在 VSCode 中使用 Claude Code 插件对接 DeepSeek，配置方式略有不同——需要通过 VSCode 的 settings.json 来注入环境变量。

2.1 安装插件

在 VSCode 扩展市场搜索 Claude Code（作者：Anthropic），点击安装。

2.2 配置 settings.json

打开 VSCode 设置（Cmd+Shift+P → Preferences: Open User Settings (JSON)），添加以下配置：

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://api.deepseek.com/anthropic"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "<你的 DeepSeek API Key>"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "deepseek-v4-pro[1m]"
    },
    {
      "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",
      "value": "deepseek-v4-pro[1m]"
    },
    {
      "name": "ANTHROPIC_DEFAULT_SONNET_MODEL",
      "value": "deepseek-v4-pro[1m]"
    },
    {
      "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",
      "value": "deepseek-v4-flash"
    },
    {
      "name": "CLAUDE_CODE_SUBAGENT_MODEL",
      "value": "deepseek-v4-flash"
    },
    {
      "name": "CLAUDE_CODE_EFFORT_LEVEL",
      "value": "max"
    }
  ]
}

注意：ANTHROPIC_AUTH_TOKEN 的值换成你自己的 DeepSeek API Key。API Key 可以在 platform.deepseek.com/api_keys 创建。

2.3 切换模型

配置完成后重启 VSCode，打开 Claude Code 面板，可以通过以下方式切换模型：

使用快捷键打开命令面板，输入 Claude Code: Switch Model
或在对话中输入 /model 选择模型

日常使用建议：

复杂任务（代码分析、重构）→ deepseek-v4-pro[1m]
简单问答、小修改 → deepseek-v4-flash

2.4 验证配置

在 Claude Code 面板中输入「你当前使用的是哪个模型？」，如果返回 DeepSeek 相关信息，说明配置成功。

注意事项

环境变量不要放在 .env 文件中。Claude Code 不读取项目 .env 文件，必须通过 shell 配置文件（CLI 方式）或 VSCode 设置（插件方式）注入。
API Key 安全。不要将 API Key 硬编码在项目文件中，确保 .zshrc 或 settings.json 不会被提交到公开仓库。
工具调用能力。DeepSeek 在工具调用（tool calling）方面与原生 Claude 模型存在差距，部分复杂的多步骤操作可能需要更多调试。
模型名称中的 [1m]。这是 DeepSeek 官方文档中 deepseek-v4-pro 的完整名称后缀，如果接口报错可以尝试去掉该后缀。

CPA Usage Keeper：CLIProxyAPI 用量追踪与可视化面板

Sat, 23 May 2026 02:04:04 GMT

CPA Usage Keeper 是一个独立的 CPA（CLIProxyAPI）用量持久化与可视化服务。它在 CPA 之上补充了 SQLite 持久化存储与统计分析能力，提供内置 Web Dashboard 用于查看 usage、pricing、request health 以及 model/API 维度的统计信息。

::github{repo="Willxup/cpa-usage-keeper"}

核心概念

CPA Usage Keeper 本质上是一个用量数据的中转 + 持久化 + 可视化层：

CLIProxyAPI (CPA)
    ↓  Redis usage 队列推送事件
CPA Usage Keeper
    ├── 消费队列 → 写入 SQLite
    ├── 定时拉取 CPA metadata
    ├── 暴露聚合 API
    └── 内置 Web Dashboard (8080 端口)

它与 CPA 的关系：

依赖 CPA：Keeper 从 CPA 的 Redis usage 队列消费事件，通过 CPA 管理接口拉取 metadata
补充 CPA：CPA 本身不做持久化存储，重启后用量数据丢失；Keeper 用 SQLite 持久保存，提供历史和趋势分析
独立部署：Keeper 是独立进程/容器，不修改 CPA 的任何配置或代码

:::tip[核心价值] 让 CPA 的用量数据"落地"——持久化存储、历史回溯、趋势分析、成本估算，一个面板全部搞定。 :::

功能特性

用量持久化：从 CPA Redis usage 队列消费事件并写入 SQLite，重启不丢数据
Dashboard 总览：请求量、Token、成本、缓存命中率、成功率和延迟一目了然
多维度筛选：按时间范围、模型、API Key 和来源筛选用量明细
分析页面：Token 趋势图、模型/API Key/AI Provider 构成、时段热力图
API Key 独立查询：可按 CPA API Key 查看专属用量
凭证页面：展示 Auth File 与 AI Provider 使用情况，支持凭证限额查询与刷新
模型价格管理：可维护模型价格，用于成本估算和统计展示
安全保护：可选密码登录保护、SQLite 备份、Docker/Docker Compose 和 systemd 部署

前置条件

使用 CPA Usage Keeper 之前，请确认 CPA 已开启 usage 统计：

# CPA 配置中必须启用
usage-statistics-enabled: true

安装部署

方式一：Docker Compose（推荐）

同时部署 CPA 和 Keeper 的最佳选择。仓库提供了 docker-compose.example.yml 作为模板：

services:
  cli-proxy-api:
    image: eceasy/cli-proxy-api:latest
    container_name: cli-proxy-api
    restart: unless-stopped
    ports:
      - "8317:8317"
      - "1455:1455"
    volumes:
      - ./cpa/config.yaml:/CLIProxyAPI/config.yaml
      - ./cpa/auths:/root/.cli-proxy-api
      - ./cpa/logs:/CLIProxyAPI/logs
    networks:
      - cpa-network

  cpa-usage-keeper:
    image: ghcr.io/willxup/cpa-usage-keeper:latest
    container_name: cpa-usage-keeper
    restart: unless-stopped
    depends_on:
      - cli-proxy-api
    ports:
      - "8080:8080"
    environment:
      TZ: Asia/Shanghai
      CPA_BASE_URL: http://cli-proxy-api:8317
      CPA_MANAGEMENT_KEY: replace-with-your-management-key
      REDIS_QUEUE_ADDR: cli-proxy-api:8317
      AUTH_ENABLED: true
      LOGIN_PASSWORD: replace-with-your-login-password
    volumes:
      - ./keeper:/data
    networks:
      - cpa-network

networks:
  cpa-network:
    driver: bridge

# 启动
docker compose up -d

# 停止
docker compose down

CPA 相关文件放在 ./cpa 目录，Keeper 数据（SQLite 数据库、日志、备份）放在 ./keeper 目录。

方式二：Docker（CPA 已在宿主机运行）

如果 CPA 已经在宿主机运行，只需单独部署 Keeper：

# 复制配置模板
cp .env.example .env
vim .env

CPA_BASE_URL=http://host.docker.internal:8317
CPA_MANAGEMENT_KEY=replace-with-your-management-key
REDIS_QUEUE_ADDR=host.docker.internal:8317
AUTH_ENABLED=true
LOGIN_PASSWORD=replace-with-your-login-password

docker run -d \
  --name cpa-usage-keeper \
  --add-host=host.docker.internal:host-gateway \
  -p 8080:8080 \
  -v "$(pwd)/keeper:/data" \
  --env-file .env \
  ghcr.io/willxup/cpa-usage-keeper:latest

:::note --add-host=host.docker.internal:host-gateway 让容器能通过 host.docker.internal 访问宿主机上的 CPA 服务。 :::

方式三：Linux 二进制

前往 Releases 页面下载对应架构的二进制包：

# 下载（请替换为实际下载地址）
curl -L -o cpa-usage-keeper.tar.gz "https://github.com/Willxup/cpa-usage-keeper/releases/latest/download/cpa-usage-keeper_linux_amd64.tar.gz"
mkdir -p cpa-usage-keeper
tar -xzf cpa-usage-keeper.tar.gz -C cpa-usage-keeper --strip-components=1
cd cpa-usage-keeper

# 配置并启动
cp .env.example .env
vim .env
./cpa-usage-keeper

systemd 常驻运行

二进制包内置了 cpa-usage-keeper.service 文件，可直接注册为 systemd 服务：

sudo cp cpa-usage-keeper.service /etc/systemd/system/cpa-usage-keeper.service
sudo sed -i "s|__CPA_USAGE_KEEPER_DIR__|$(pwd)|g" /etc/systemd/system/cpa-usage-keeper.service
sudo systemctl daemon-reload
sudo systemctl enable --now cpa-usage-keeper

常用管理命令：

sudo systemctl status cpa-usage-keeper   # 查看服务状态
sudo journalctl -u cpa-usage-keeper -f   # 实时查看日志
sudo systemctl restart cpa-usage-keeper  # 重启服务

配置详解

所有配置通过环境变量（.env 文件）管理。复制模板后按需修改：

cp .env.example .env

最小必填

变量	必填	默认值	说明
`CPA_BASE_URL`	是	-	Keeper 服务端访问 CPA 的地址。Docker Compose 内通常是 `http://cli-proxy-api:8317`
`CPA_MANAGEMENT_KEY`	是	-	CPA management key（即 CPA `config.yaml` 中的 `secret-key`），用于读取 CPA 管理接口数据

Web 访问与反代

变量	必填	默认值	说明
`APP_PORT`	否	`8080`	Keeper HTTP 监听端口
`APP_BASE_PATH`	否	根路径	子路径部署前缀，例如 `/keeper`
`CPA_PUBLIC_URL`	否	浏览器同源根路径	浏览器访问 CPA 的公开地址，用于"返回 CPA"跳转

:::tip[APP_BASE_PATH 说明] APP_BASE_PATH 必须为空或以 / 开头。例如 /cpa 是正确的，/cpa/ 会自动规范为 /cpa。如果你通过 Nginx 的 /keeper/ 路径反代，需设置 APP_BASE_PATH=/keeper。 :::

登录保护

变量	必填	默认值	说明
`AUTH_ENABLED`	否	`false`	是否启用登录保护
`LOGIN_PASSWORD`	鉴权启用时必填	-	登录密码
`AUTH_SESSION_TTL`	否	`168h`	登录 session 有效时长

:::warning[安全提示] 公网部署务必设置 AUTH_ENABLED=true 并配置强密码，防止用量数据被未授权访问。 :::

时区与请求

变量	必填	默认值	说明
`TZ`	否	`Asia/Shanghai`	统计和展示使用的时区
`REQUEST_TIMEOUT`	否	`30s`	请求 CPA HTTP 接口的超时时间
`TLS_SKIP_VERIFY`	否	`false`	跳过 CPA HTTPS 证书验证（仅自签名证书时启用）

Redis 队列高级配置

变量	必填	默认值	说明
`REDIS_QUEUE_ADDR`	否	CPA 主机 + 8317	CPA Redis/RESP TCP 地址
`REDIS_QUEUE_TLS`	否	`false`	是否使用 TLS 连接 Redis 队列
`REDIS_QUEUE_BATCH_SIZE`	否	`10000`	每次最多拉取的队列记录数
`REDIS_QUEUE_IDLE_INTERVAL`	否	`1s`	队列为空时的检查间隔

一般保持默认值即可，只有 CPA 的 Redis 端口不是默认 8317 时才需要显式设置。

存储、日志与备份

变量	必填	默认值	说明
`WORK_DIR`	否	`./data`	工作目录（数据库、日志、备份）
`LOG_LEVEL`	否	`info`	日志级别：`debug` / `info` / `warn` / `error`
`LOG_FILE_ENABLED`	否	`true`	是否写入持久化日志文件
`LOG_RETENTION_DAYS`	否	`7`	日志保留天数，`0` 不自动清理
`BACKUP_ENABLED`	否	`true`	是否启用 SQLite 数据库备份
`BACKUP_INTERVAL`	否	`24h`	数据库备份间隔
`BACKUP_RETENTION_DAYS`	否	`7`	备份保留天数

内置 HTTPS

变量	必填	默认值	说明
`TLS_ENABLED`	否	`false`	是否让 Keeper 自己启用 HTTPS
`TLS_CERT_FILE`	启用时必填	-	HTTPS 证书文件路径
`TLS_KEY_FILE`	启用时必填	-	HTTPS 私钥文件路径

通常建议在 Nginx 或 Caddy 等反向代理层处理 HTTPS，而不是让 Keeper 自己处理。

Dashboard 功能导览

启动服务后，访问 http://服务器IP:8080 进入 Dashboard。

总览页面

首页展示核心指标卡片：请求总量、Token 消耗、估算成本、缓存命中率、成功率、平均延迟。下方有请求趋势图和模型分布图，帮助你快速了解整体使用情况。

用量明细

支持按时间范围（Today / 7天 / 30天 / 自定义）、模型、API Key 和来源多维度筛选。每条记录包含请求时间、模型名称、Token 数、延迟、是否缓存命中、是否成功等字段。

分析页面

提供三个维度的深度分析：

Token 趋势：按天/按小时查看 Token 消耗变化
构成分析：模型占比、API Key 用量分布、AI Provider 占比
时段热力图：一周内各时段的请求密度分布，直观发现使用高峰

API Key 独立查询

如果你在 CPA 中配置了多个 api-keys（多用户场景），Keeper 支持按 Key 独立查询用量。每个 Key 对应一个专属页面，方便团队场景下的用量核算。

凭证页面

展示 CPA 中各 Auth File 的认证状态、对应的 AI Provider、剩余配额等信息。支持一键刷新凭证状态。

模型价格管理

Keeper 内置了主流模型的默认价格，但你可以在 Dashboard 中自定义价格，用于更准确的成本估算。

Nginx 反向代理

在生产环境中，建议通过 Nginx 反代访问 Keeper，统一处理 HTTPS 和路径：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # 如果部署在子路径 /keeper/
    location /keeper/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

子路径部署时记得在 .env 中设置 APP_BASE_PATH=/keeper。

如果 CPA 管理页和 Keeper 使用同一域名，"返回 CPA"按钮会自动跳转到同源 /management.html，无需额外配置 CPA_PUBLIC_URL。如果 CPA 在其他域名或端口，请设置：

# 示例：CPA 部署在独立域名
CPA_PUBLIC_URL=https://cpa.example.com

数据说明

了解数据流转有助于排查问题：

数据来源：Keeper 从 CPA 的 Redis usage 队列消费每一条请求事件
存储方式：SQLite 数据库，文件位于 WORK_DIR/app.db
Metadata 同步：Keeper 定时从 CPA 管理接口拉取模型列表、Auth File 状态、配额信息等
数据清理：Redis inbox 原始消息会自动清理——成功数据保留到当天结束后清理，失败数据保留 7 天
脱敏处理：面向浏览器的 API 会对 key-like 的 source/lookup 字段做脱敏或稳定公开标识映射，但不会修改数据库原始值

常见问题

启动后 Dashboard 没有数据？

确认 CPA 的 config.yaml 中 usage-statistics-enabled: true 已设置
确认 CPA_MANAGEMENT_KEY 的值与 CPA 的 secret-key 一致
确认 REDIS_QUEUE_ADDR 能连通 CPA 的 8317 端口
发起几个 API 请求后再查看，数据从 Redis 队列消费有一定延迟（默认空闲时 1s 检查一次）

CPA 和 Keeper 的网络不通？

Docker Compose 部署时两者在同一 cpa-network 下，服务名 cli-proxy-api 即可互通。Docker 单独部署时使用 host.docker.internal 访问宿主机。检查防火墙是否放行对应端口。

如何备份数据？

Keeper 内置自动备份功能（默认每 24 小时备份一次），备份文件在 WORK_DIR/backups/。你也可以手动备份 WORK_DIR/app.db 文件——SQLite 单文件数据库，直接复制即可。

数据库文件越来越大？

SQLite 数据库会随着用量数据积累而增长。目前 Keeper 暂不支持自动清理历史数据，如需清理可考虑定期重建。日志文件默认保留 7 天自动清理。

登录密码忘了？

子路径部署后页面白屏？

检查 APP_BASE_PATH 是否正确设置，以及 Nginx 的 proxy_pass 是否正确传递了路径前缀。确保静态资源的路径也正确映射。

安全建议

:::warning[生产环境清单]

[ ] AUTH_ENABLED=true 并设置强密码（16 位以上随机字符）
[ ] 在反向代理层配置 HTTPS（Nginx / Caddy），不直接暴露 8080 端口
[ ] 数据库备份文件不做加密，妥善保管 WORK_DIR/backups/ 目录
[ ] 登录 session 存于内存，服务重启后失效——这是设计如此，不必疑惑
[ ] 定期检查 LOG_RETENTION_DAYS 和 BACKUP_RETENTION_DAYS，避免磁盘占满 :::

DeepSeek-TUI：终端原生 AI 编程智能体

Fri, 15 May 2026 02:11:25 GMT

DeepSeek-TUI 是一款面向 DeepSeek V4 模型的终端原生编程智能体，完全在命令行中运行，提供文件操作、Shell 执行、Git 管理、网页浏览、子智能体协调等能力，通过键盘驱动的 TUI 界面交互。

::github{repo="Hmbown/DeepSeek-TUI"}

核心特性

特性	说明
100 万 Token 上下文	完整窗口支持，带压缩追踪和前缀缓存遥测
流式推理	实时观察模型思维链
自动模型选择	根据任务复杂度自动在 Flash 和 Pro 之间切换
三种交互模式	Plan（只读）/ Agent（审批）/ YOLO（自动批准）
持久任务队列	任务在应用重启后仍可恢复
子智能体并行	最多 10 个（可配至 20 个）并发背景任务
LSP 诊断集成	编辑后实时显示 rust-analyzer、pyright、gopls 等诊断信息
MCP 服务器	通过 Model Context Protocol 扩展工具能力

安装

npm（推荐，无需 Node.js 运行时）

npm install -g deepseek-tui

Cargo（从 Rust 源码编译）

cargo install deepseek-tui-cli --locked
cargo install deepseek-tui --locked

Homebrew（macOS）

brew tap Hmbown/deepseek-tui
brew install deepseek-tui

直接下载二进制

前往 Releases 页面下载对应平台的预编译二进制文件：

Linux x64 / ARM64
macOS (Intel / Apple Silicon)
Windows x64

Docker

# 创建持久化数据卷
docker volume create deepseek-tui-home

# 启动容器（挂载当前目录为工作区）
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v deepseek-tui-home:/home/deepseek/.deepseek \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/hmbown/deepseek-tui:latest

:::tip Docker 方式通过数据卷持久化配置和会话数据，容器删除后数据不丢失。 :::

配置 API

DeepSeek 官方（推荐）

# 设置提供商
deepseek auth set --provider deepseek

# 设置 API Key（从 platform.deepseek.com 获取）
export DEEPSEEK_API_KEY="your_api_key_here"

或写入 Shell 配置文件永久生效：

echo 'export DEEPSEEK_API_KEY="your_api_key_here"' >> ~/.zshrc
source ~/.zshrc

NVIDIA NIM

deepseek auth set --provider nvidia-nim --api-key "YOUR_KEY"

OpenRouter

deepseek auth set --provider openrouter --api-key "YOUR_KEY"

# 指定模型调用
deepseek --provider openrouter --model deepseek/deepseek-v4-pro

自托管（Ollama / vLLM）

# Ollama 本地部署
deepseek auth set --provider ollama --base-url "http://localhost:11434"

# vLLM
deepseek auth set --provider vllm --base-url "http://localhost:8000" --api-key "YOUR_KEY"

配置文件

用户级配置：~/.deepseek/config.toml
工作区级配置：.deepseek/config.toml（工作区配置优先级更高）

[tui]
locale = "zh-Hans"          # 界面语言：en / ja / zh-Hans / pt-BR，留空自动检测
theme = "catppuccin"        # 主题：catppuccin / tokyo-night / dracula / gruvbox / light / dark

[agent]
max_subagents = 10          # 最大并发子智能体数量（最高 20）
auto_mode = true            # 启用自动模型选择

[context]
user_memory = true          # 跨会话的用户记忆注入

可用主题： catppuccin、tokyo-night、dracula、gruvbox，以及内置的 light / dark，运行时用 /theme 命令切换。

启动与使用模式

基本启动

# 交互模式启动（默认 Agent 模式）
deepseek

# 一次性查询（非交互）
deepseek "解释这个文件的作用" @src/main.rs

# 指定工作目录
deepseek --dir /path/to/project

三种交互模式

Plan 模式（只读探索）

deepseek --plan

只读取文件和分析代码，不执行任何修改操作。适合先理解项目结构再决定行动。

Agent 模式（默认）

deepseek

每次工具调用（文件写入、Shell 命令等）都需要用户审批确认，安全可控。

YOLO 模式（自动批准）

deepseek --yolo

自动批准所有工具调用，适合可信任的工作区或自动化脚本。

:::caution[YOLO 模式注意事项] YOLO 模式下 AI 会直接执行所有操作，建议仅在有版本控制的项目中使用，确保误操作可回滚。 :::

模型选择

# 自动选择（根据任务复杂度选 Flash 或 Pro）
deepseek --model auto

# 强制使用 Pro
deepseek --model deepseek-v4-pro

# 强制使用 Flash（速度快，成本低）
deepseek --model deepseek-v4-flash

Auto 模式会在每轮对话前用 Flash 模型做预检，判断任务是否需要 Pro 的推理能力，从而在成本和质量间自动平衡。

Headless HTTP/SSE 模式

# 启动 HTTP API 服务（无界面）
deepseek serve --http --port 3000

适合将 DeepSeek-TUI 作为后端服务集成到其他系统。

内置工具

DeepSeek-TUI 内置以下工具，AI 可自主调用（Agent 模式下需用户审批）：

工具类别	功能
文件操作	读写、创建、删除、重命名工作区文件
Shell 执行	运行任意 Shell 命令，带当前目录验证和安全检查
Git 管理	提交、分支、diff、stash 等版本控制操作
网页浏览	搜索网页、抓取 URL 内容（含 SSRF 防护）
补丁应用	通过 `apply-patch` 应用代码修改
子智能体	生成具有独立上下文和工具注册表的并发后台任务
MCP 服务器	连接 Model Context Protocol 服务器扩展工具
RLM	持久 REPL 会话，用低成本 Flash 模型做批量分析

附加文件/目录上下文

在输入框中使用 @ 附加文件或目录：

@src/main.rs 帮我重构这个函数
@./tests/ 分析测试覆盖率

子智能体系统

子智能体允许并发后台执行复杂任务：

非阻塞启动： agent_open 立即返回，子智能体在后台独立运行。

并行执行： 默认最多 10 个子智能体并发（可配置至 20 个）。

完成通知： 子智能体完成时发送结构化事件，包含摘要、证据列表和指标。

按需读取结果： 大型对话日志使用 var_handle 引用，通过 handle_read 配合切片、范围查询或 JSONPath 投影按需读取。

典型用法示例：

# 在对话框中让 AI 并行分析多个模块
分析这个项目的所有模块，为每个模块启动一个子智能体并行工作，最后汇总报告

键盘快捷键

快捷键	功能
`Tab`	自动补全 `/` 或 `@`；或队列草稿 / 切换模式（视上下文）
`Shift+Tab`	循环切换推理强度：关闭 → 高 → 最大
`F1`	打开可搜索的帮助面板
`Esc`	返回 / 关闭对话框
`Ctrl+K`	命令面板
`Ctrl+R`	恢复历史会话
`Alt+R`	搜索历史 / 恢复草稿
`Ctrl+S`	暂存当前草稿
`↑`（输入框开头）	移除上一行附件

:::note 完整快捷键列表可在项目的 docs/KEYBINDINGS.md 查看，或按 F1 在应用内搜索。 :::

LSP 诊断集成

每次文件编辑后，DeepSeek-TUI 自动调用对应语言服务器提供内联错误/警告反馈：

语言	LSP 服务器
Rust	`rust-analyzer`
Python	`pyright`
TypeScript / JavaScript	`typescript-language-server`
Go	`gopls`
C / C++	`clangd`

AI 会读取诊断信息并自动修复，形成"编辑 → 检查 → 修复"的闭环。

会话持久化与回滚

DeepSeek-TUI 通过旁路 Git 记录实现会话快照：

# 恢复上次会话
deepseek   # 然后按 Ctrl+R 选择历史会话

# 查看会话历史
deepseek sessions list

长时间任务中途断开后，重新启动并恢复会话，AI 会从中断点继续执行。

Skills 系统

Skills 是可组合的指令包，可从 GitHub 安装：

# 安装内置 Skill
deepseek skills install <skill-name>

# 从 GitHub 安装
deepseek skills install github:username/repo

Skills 让你为特定项目或工作流定制 AI 行为，例如代码审查规范、提交信息格式等。

价格参考

模型	上下文	输入（缓存命中）	输入（缓存未命中）	输出
deepseek-v4-pro	100 万 token	$0.003625/1M*	$0.435/1M*	$0.87/1M*
deepseek-v4-flash	100 万 token	$0.0028/1M	$0.14/1M	$0.28/1M

* Pro 价格为限时 75% 折扣，有效期至 2026 年 5 月 31 日。

DeepSeek-TUI 实时显示每轮对话的 Token 消耗和费用，并统计缓存命中/未命中情况，帮助控制成本。

:::tip[降低成本的技巧]

使用 --model auto 让简单任务自动切换到 Flash 模型
通过 @ 精确附加相关文件，避免传入不必要的上下文
利用前缀缓存：相同前缀的对话可大幅降低输入 Token 费用 :::

常用工作流示例

理解新项目

deepseek --plan
> @./ 帮我分析这个项目的整体架构，生成一份架构文档

修复 Bug

deepseek
> 运行测试套件，找出失败的测试并修复对应的 Bug

代码重构

deepseek --yolo
> 将 src/ 目录下所有 JavaScript 文件迁移到 TypeScript，保持逻辑不变

并行分析

deepseek
> 为每个子目录启动一个子智能体，并行分析代码质量，最后汇总评分报告

CLIProxyAPI：将 AI CLI 工具统一转换为标准 API 服务

Wed, 22 Apr 2026 02:04:04 GMT

CLIProxyAPI 是一个将 Gemini CLI、Claude Code、ChatGPT Codex、Grok Build、Antigravity 等 AI CLI 工具包装成 OpenAI / Gemini / Claude / Codex 兼容 API 服务的代理层，让你通过统一的标准 API 接口免费调用这些模型。

::github{repo="router-for-me/CLIProxyAPI"}

核心概念

CLIProxyAPI 本质上是一个中间层代理：

你的客户端 (Cursor / NextChat / Python SDK / curl)
        ↓  标准 API 请求 (OpenAI / Claude / Gemini 格式)
   CLIProxyAPI  (8317 端口)
        ↓  调用本地/远程 CLI 工具
Gemini CLI / Claude Code / Codex / Grok Build
        ↓  OAuth 免费额度
     云端 AI 模型

支持的 CLI 后端：

CLI 工具	对应模型	免费额度
Gemini CLI	Gemini 2.5 Pro / Flash	每日大量免费请求
Claude Code	Claude Sonnet / Opus	按月计费账户
ChatGPT Codex	GPT-4o / o3	Plus 会员额度
Grok Build	Grok 3 / 4	xAI 免费额度
Antigravity	多模型	自定义

支持的 API 协议：

OpenAI Chat Completions (/v1/chat/completions)
OpenAI Responses API (/v1/responses)
Anthropic Messages (/v1/messages)
Google Gemini (/v1beta/models/:model/generateContent)

:::tip[核心价值] 通过一个本地/服务器服务，用标准 API 接口调用多个免费 AI 额度，Cursor、NextChat、OpenClaw 等工具无缝接入。 :::

安装

方式一：二进制文件（推荐新手）

前往 Releases 页面下载对应系统的压缩包，解压后直接运行。

Linux / macOS：

# 下载（以 Linux amd64 为例，请替换为最新版本号）
wget https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/CLIProxyAPI-linux-amd64.tar.gz
tar -xzf CLIProxyAPI-linux-amd64.tar.gz
chmod +x cliproxyapi

# 初始化默认配置
./cliproxyapi init

# 启动服务
./cliproxyapi start

macOS（Homebrew）：

brew tap router-for-me/tap
brew install cliproxyapi
cliproxyapi init && cliproxyapi start

Windows（PowerShell）：

# 下载 windows-amd64.zip 后解压，在目录内执行
.\cliproxyapi.exe init
.\cliproxyapi.exe start

方式二：Docker（推荐服务器部署）

# 创建工作目录
mkdir -p ~/cliproxyapi/{auths,logs}
cd ~/cliproxyapi

# 下载示例配置
curl -O https://raw.githubusercontent.com/router-for-me/CLIProxyAPI/main/config.example.yaml
cp config.example.yaml config.yaml

# 拉取并启动
docker run -d \
  --name cliproxyapi \
  --restart unless-stopped \
  -p 8317:8317 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/auths:/app/auths \
  -v $(pwd)/logs:/app/logs \
  ghcr.io/router-for-me/cliproxyapi:latest

方式三：Docker Compose（推荐生产环境）

services:
  cliproxyapi:
    image: ghcr.io/router-for-me/cliproxyapi:latest
    container_name: cliproxyapi
    restart: unless-stopped
    ports:
      - "8317:8317"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./auths:/app/auths
      - ./logs:/app/logs
    environment:
      - TZ=Asia/Shanghai

docker compose up -d

配置文件详解

CLIProxyAPI 通过 config.yaml 管理所有配置，支持热重载，修改后即时生效无需重启。

# ── 服务器基础配置 ──────────────────────────────
server:
  host: ""          # 留空表示监听所有网卡（0.0.0.0）
  port: 8317        # 服务端口，默认 8317
  # tls:            # 可选：开启 HTTPS
  #   cert: /path/to/cert.pem
  #   key: /path/to/key.pem

# ── 远程管理 / WebUI ──────────────────────────────
remote-management:
  allow-remote: true      # 是否允许远程访问管理接口
  secret-key: "your-strong-password"  # WebUI 登录密码，务必修改！

# ── 认证文件目录 ──────────────────────────────────
auth-dir: "./auths"       # 存放 OAuth 认证文件的目录

# ── 各 CLI 后端配置 ───────────────────────────────
providers:

  # Gemini CLI
  gemini:
    enabled: true
    api-keys:             # 客户端调用时使用的 API Key（自定义，随意填写）
      - "sk-gemini-your-key-1"
      - "sk-gemini-your-key-2"
    load-balance: round-robin   # round-robin | fill-first

  # Claude Code
  claude:
    enabled: true
    api-keys:
      - "sk-claude-your-key-1"
    load-balance: round-robin

  # ChatGPT Codex
  codex:
    enabled: false
    api-keys:
      - "sk-codex-your-key-1"

  # Grok Build
  grok:
    enabled: false
    api-keys:
      - "sk-grok-your-key-1"

# ── 全局 API Key（可同时访问所有后端）────────────
global-api-keys:
  - "sk-global-master-key"

# ── 日志配置 ──────────────────────────────────────
log:
  level: info             # debug | info | warn | error
  dir: "./logs"

:::warning[安全提示] secret-key 是 WebUI 的登录密码，生产环境务必设置强密码。api-keys 是自定义的认证凭据，客户端连接时填写这里配置的值。 :::

负载均衡策略

策略	说明	适用场景
`round-robin`	轮询均匀分配到所有账号	多号薅配额，最大化吞吐
`fill-first`	优先压满第一个账号，满了才切换	主力号 + 备用号组合

CLI 认证授权

Gemini CLI 授权

# 本地安装 Gemini CLI（需要 Node.js 18+）
npm install -g @google/gemini-cli

# 触发 OAuth 授权（会打开浏览器）
gemini auth login

# 授权成功后，将认证文件复制到 auths 目录
# CLIProxyAPI 会自动读取该目录下的认证信息

:::note Gemini 个人 Google 账号每天有大量免费请求额度（Gemini 2.5 Pro 约 1000 次/天），特别适合轻量使用场景。 :::

Claude Code 授权

# 安装 Claude Code（需要 Node.js 18+）
npm install -g @anthropic-ai/claude-code

# 触发 OAuth 授权
claude auth login

# 会在浏览器中完成 Anthropic 账号授权
# 授权后认证文件默认在 ~/.claude/ 目录

:::tip Claude Code 使用 Claude Max 订阅的额度，适合需要更高质量代码生成的场景。 :::

ChatGPT Codex 授权

# 安装 Codex CLI
npm install -g @openai/codex

# 登录 OpenAI 账号
codex auth login

Grok Build 授权

# 安装 Grok Build
npm install -g @xai/grok-build

# 使用 xAI 账号授权
grok auth login

多账号管理

CLIProxyAPI 支持同一个后端绑定多个账号（认证文件），实现轮询负载均衡：

auths/
├── gemini-account1.json
├── gemini-account2.json
├── gemini-account3.json
├── claude-account1.json
└── codex-account1.json

每个认证文件对应一个账号，CLIProxyAPI 按配置的策略自动分配请求。

WebUI 管理界面

启动服务后，访问 http://服务器IP:8317/management.html 进入后台管理：

账号状态：实时查看各 CLI 账号的认证状态和剩余配额
配置管理：在线修改 config.yaml，热重载即时生效
日志查看：实时查看请求日志和错误信息
上传认证：直接上传 OAuth 认证文件，无需手动拷贝

管理页面地址: http://YOUR_SERVER:8317/management.html
密码: config.yaml 中的 secret-key

API 调用示例

CLIProxyAPI 服务默认在 http://localhost:8317 监听。

cURL 调用

OpenAI 格式（Chat Completions）：

curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-gemini-your-key-1" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

Anthropic 格式（Messages）：

curl http://localhost:8317/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-claude-your-key-1" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "写一个快速排序算法"}
    ]
  }'

流式输出（Streaming）：

curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-gemini-your-key-1" \
  -d '{
    "model": "gemini-2.5-pro",
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一篇关于量子计算的科普文章"}
    ]
  }'

Python SDK 调用

from openai import OpenAI

# 指向本地 CLIProxyAPI 服务
client = OpenAI(
    base_url="http://localhost:8317/v1",
    api_key="sk-gemini-your-key-1"
)

# 普通调用
response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[
        {"role": "user", "content": "解释一下什么是 RAG 技术"}
    ]
)
print(response.choices[0].message.content)

# 流式调用
stream = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "写一个 Python 爬虫示例"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import anthropic

# 使用 Anthropic SDK 调用 Claude 后端
client = anthropic.Anthropic(
    base_url="http://localhost:8317",
    api_key="sk-claude-your-key-1"
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用 Go 语言实现一个并发安全的缓存"}
    ]
)
print(message.content[0].text)

查询可用模型

# 列出所有可用模型
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-gemini-your-key-1"

接入主流客户端

Cursor

打开 Cursor → Settings → Models
Base URL: http://localhost:8317/v1
API Key: 填入 config.yaml 中配置的任意 api-keys 值
选择模型（如 gemini-2.5-pro）后保存

:::tip 如果 Cursor 和 CLIProxyAPI 在同一台机器，使用 http://localhost:8317/v1；如果是远程服务器，替换为服务器 IP。 :::

NextChat / ChatGPT-Next-Web

打开 NextChat 设置
自定义接口: 勾选
接口地址: http://localhost:8317
API Key: 填入对应的 api-keys
自定义模型名称: gemini-2.5-pro,claude-sonnet-4-5

OpenClaw

设置 → Provider → 自定义
Base URL: http://localhost:8317
API Type: openai-compatible
API Key: sk-global-master-key

:::caution[注意路径] OpenClaw 接入时 Base URL 不要带 /v1 后缀，因为 OpenClaw 会自动追加路径，否则会出现 /v1/v1/messages 404 错误。 :::

Open WebUI

# 在 Open WebUI 的环境变量中设置
OPENAI_API_BASE_URL=http://localhost:8317/v1
OPENAI_API_KEY=sk-gemini-your-key-1

Continue（VSCode 插件）

{
  "models": [
    {
      "title": "Gemini 2.5 Pro (Free)",
      "provider": "openai",
      "model": "gemini-2.5-pro",
      "apiBase": "http://localhost:8317/v1",
      "apiKey": "sk-gemini-your-key-1"
    },
    {
      "title": "Claude Sonnet",
      "provider": "anthropic",
      "model": "claude-sonnet-4-5",
      "apiBase": "http://localhost:8317",
      "apiKey": "sk-claude-your-key-1"
    }
  ]
}

Nginx 反向代理（生产环境）

在服务器部署时，建议套一层 Nginx + HTTPS：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:8317;
        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_read_timeout 300s;   # 流式响应需要较长超时
        proxy_buffering    off;    # 关闭缓冲，确保流式传输即时转发
    }
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

# 申请证书（Certbot）
certbot --nginx -d your-domain.com

# 重载 Nginx
nginx -s reload

常见问题

认证失效怎么办？

CLI 工具的 OAuth Token 有有效期，过期后需要重新授权：

# 重新授权 Gemini
gemini auth login

# 重新授权 Claude Code  
claude auth login

# 将新生成的认证文件复制到 auths 目录
# CLIProxyAPI 会热重载自动识别

如何查看请求日志？

# Docker 部署查看日志
docker logs -f cliproxyapi

# 或访问 WebUI 管理页面的日志面板
http://YOUR_SERVER:8317/management.html

模型名称不对？

CLIProxyAPI 支持模型名称映射，可以在 config.yaml 中自定义：

model-mapping:
  "gpt-4o": "gemini-2.5-pro"       # 把 gpt-4o 请求转发到 Gemini
  "claude-3-5-sonnet": "claude-sonnet-4-5"

端口被占用？

修改 config.yaml 中的 port 字段，或 Docker 部署时修改端口映射：

docker run -p 9000:8317 ...  # 映射到宿主机 9000 端口

流式响应中断？

检查 Nginx 配置中是否设置了 proxy_buffering off 和足够长的 proxy_read_timeout。

安全建议

:::warning[生产环境清单]

[ ] secret-key 设置为强密码（16 位以上随机字符）
[ ] api-keys 不要使用简单字符串
[ ] 服务器防火墙只开放必要端口（建议套 Nginx + HTTPS，不直接暴露 8317）
[ ] 定期轮换 api-keys
[ ] allow-remote: false 如果不需要远程访问管理接口 :::

Telegram 双向机器人：验证码版部署

Fri, 14 Nov 2025 23:40:01 GMT

前言

本周双向私信机器人被轰炸，我一天收到了上千条垃圾广告。故拿AI搓了一个

Github

Telegram 消息转发机器人

具有图片验证码和用户管理功能的 Telegram 消息转发机器人。

✨ 特性

🔐 图片验证码防垃圾消息
💬 主人回复功能（直接回复转发消息）
🚫 用户拉黑/解除拉黑（/block 和 /unblock 命令）
☁️ Supabase 云数据库（数据永不丢失）
🐳 Docker 支持

🚀 快速开始

先配置数据库

配置 Supabase 数据库

在 Supabase 创建项目，然后在 SQL Editor 中执行：

-- 消息映射表
CREATE TABLE message_mappings (
  id BIGSERIAL PRIMARY KEY,
  forwarded_message_id BIGINT UNIQUE NOT NULL,
  user_id BIGINT NOT NULL,
  username TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 已验证用户表
CREATE TABLE verified_users (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT UNIQUE NOT NULL,
  username TEXT,
  verified_at TIMESTAMPTZ DEFAULT NOW()
);

-- 待验证用户表
CREATE TABLE pending_verifications (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT UNIQUE NOT NULL,
  code TEXT NOT NULL,
  attempts INTEGER DEFAULT 0,
  expires_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 拉黑用户表
CREATE TABLE blocked_users (
  id BIGSERIAL PRIMARY KEY,
  user_id BIGINT UNIQUE NOT NULL,
  blocked_at TIMESTAMPTZ DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_message_mappings_forwarded_id ON message_mappings(forwarded_message_id);
CREATE INDEX idx_verified_users_user_id ON verified_users(user_id);
CREATE INDEX idx_pending_verifications_user_id ON pending_verifications(user_id);
CREATE INDEX idx_blocked_users_user_id ON blocked_users(user_id);

🐳 Docker 部署

方法一：直接运行

docker run -d \
  --name telegram-bot \
  --restart unless-stopped \
  -e BOT_TOKEN="你的Bot_Token" \
  -e OWNER_ID="你的用户ID" \
  -e SUPABASE_URL="你的Supabase_URL" \
  -e SUPABASE_KEY="你的Supabase_Key" \
  -v $(pwd)/logs:/app/logs \
  ghcr.io/ham0mer/tgbot:latest

方法二：使用 docker-compose

修改 docker-compose.yml：

services:
  telegram-bot:
    image: ghcr.io/ham0mer/tgbot:latest
    container_name: telegram-bot
    restart: unless-stopped
    environment:
      - BOT_TOKEN=${BOT_TOKEN}
      - OWNER_ID=${OWNER_ID}
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_KEY=${SUPABASE_KEY}
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

然后启动：

docker compose up -d

启动并查看日志

docker compose up -d && docker compose logs -f

🔄 更新镜像

更新到最新版本

docker compose pull && docker compose down && docker compose up -d && docker compose logs -f
docker image prune

使用说明

用户使用

发送 /start 获取验证码
回复验证码完成验证
验证后可正常发送消息

主人功能

回复用户：直接回复转发的消息
拉黑用户：回复用户消息并发送 /block
解除拉黑：回复用户消息并发送 /unblock

generate_204：网络连通性检测服务汇总

Mon, 27 Oct 2025 13:19:07 GMT

什么是 generate_204

generate_204 是一种用于检测网络联通性的轻量 HTTP 接口。设备连接到 Wi-Fi 后，操作系统会自动向预设 URL 发送 HTTP 请求，根据返回的状态码判断当前网络状态：

返回 204 No Content 或 200 OK → 网络畅通，可正常上网
返回 302 重定向 → 可能处于需要认证的 Captive Portal（如酒店/机场 Wi-Fi 登录页）
请求超时 / 无响应 → 网络不通或被封锁

:::note "204" 的含义是 HTTP 状态码 No Content（无内容），服务器返回空响应体，流量消耗极少，非常适合作为周期性心跳检测。 :::

工作原理

设备连接 Wi-Fi
    ↓
发送 HTTP GET → http://www.gstatic.com/generate_204
    ↓
┌───────────────────────────────────────┐
│  返回 204   →  网络正常，无感知通过   │
│  返回 302   →  弹出 Portal 登录界面   │
│  超时/其他  →  显示"无互联网访问"     │
└───────────────────────────────────────┘

各主流操作系统使用不同的检测地址：

系统 / 浏览器	使用的检测 URL
Android (AOSP)	`http://connectivitycheck.gstatic.com/generate_204`
Chrome / ChromeOS	`http://www.gstatic.com/generate_204`
Microsoft Edge	`http://edge-http.microsoft.com/captiveportal/generate_204`
Windows (NCSI)	`http://www.msftconnecttest.com/connecttest.txt`
macOS / iOS	`http://captive.apple.com`
Firefox	`http://detectportal.firefox.com/canonical.html`
MIUI (小米)	`http://connect.rom.miui.com/generate_204`
HarmonyOS (华为)	`http://connectivitycheck.platform.hicloud.com/generate_204`

服务地址汇总

:::tip 下表中的"体验评分"为粗略延迟测试（满分 10 分），实际结果因地区和时段而异，仅供参考。 :::

国际服务

服务提供者	链接	大陆体验	境外体验	HTTP / HTTPS 响应码	IP 版本
Google	`http://www.gstatic.com/generate_204`	5	10	204 / 204	4+6
Google	`http://www.google.com/generate_204`	0	10	204 / 204	4+6
Google	`http://connectivitycheck.gstatic.com/generate_204`	4	10	204 / 204	4+6
Google	`http://connectivitycheck.android.com/generate_204`	3	10	204 / 204	4+6
Google	`http://clients3.google.com/generate_204`	3	10	204 / 204	4+6
Google	`http://play.googleapis.com/generate_204`	2	10	204 / 204	4+6
Google	`http://www.google-analytics.com/generate_204`	6	10	204 / 204	4+6
Apple	`http://captive.apple.com`	3	10	200 / 200	4+6
Apple 🔥	`http://www.apple.com/library/test/success.html`	7	10	200 / 200	4+6
Microsoft	`http://www.msftconnecttest.com/connecttest.txt`	5	10	200 / error	4
Microsoft	`http://edge-http.microsoft.com/captiveportal/generate_204`	5	10	204 / 204	4
Microsoft	`http://www.msftncsi.com/ncsi.txt`	4	10	200 / 200	4
Cloudflare 🔥	`http://cp.cloudflare.com/`	4	10	204 / 204	4+6
Firefox	`http://detectportal.firefox.com/success.txt`	5	10	200 / 200	4+6
Firefox	`http://detectportal.firefox.com/canonical.html`	5	10	200 / 200	4+6
GNOME	`http://nmcheck.gnome.org/check_network_status.txt`	2	8	200 / 200	4+6
V2EX	`http://www.v2ex.com/generate_204`	0	10	204 / 301	4+6

国内服务

服务提供者	链接	大陆体验	境外体验	HTTP / HTTPS 响应码	IP 版本
小米 / MIUI 🔥	`http://connect.rom.miui.com/generate_204`	10	4	204 / 204	4
华为 / HiCloud	`http://connectivitycheck.platform.hicloud.com/generate_204`	10	5	204 / 204	4
Vivo	`http://wifi.vivo.com.cn/generate_204`	10	5	204 / 204	4

:::warning 国内服务（小米、华为、Vivo）在境外网络环境下延迟较高甚至不可达，不建议在海外服务器上使用。反之，Google 系地址在大陆网络中通常被封锁，大陆用户推荐使用 Apple、Cloudflare 或国内厂商地址。 :::

常见使用场景

1. 代理软件联通性测试

主流代理工具（如 Clash、sing-box）的延迟测试（URL Test）默认使用 http://www.gstatic.com/generate_204，可根据需要替换为延迟更低的地址：

# Clash / Mihomo 示例
url-test:
  url: "http://cp.cloudflare.com/"   # 或使用 apple.com/library/test/success.html
  interval: 300

2. 替换 Android 默认检测地址（去除感叹号）

在 Android 设备（需 Root 或 ADB）中修改检测地址，可将 Google 服务替换为国内可访问的地址，解决 Wi-Fi 图标感叹号问题：

# 通过 ADB 修改（Android 7+）
adb shell settings put global captive_portal_http_url "http://connect.rom.miui.com/generate_204"
adb shell settings put global captive_portal_https_url "https://connect.rom.miui.com/generate_204"

:::caution 修改系统检测地址可能影响 Captive Portal 的自动弹出功能（如机场/酒店 Wi-Fi 登录页），请根据实际需求谨慎操作。 :::

3. 自建检测服务

可以用 Nginx 快速搭建私有 generate_204 端点，适合企业内网或私有部署场景：

location /generate_204 {
    return 204;
}

选择建议

使用环境	推荐地址
大陆用户，追求速度	`http://www.apple.com/library/test/success.html`
大陆用户，Android 原生	`http://connect.rom.miui.com/generate_204`
境外服务器 / 代理测速	`http://cp.cloudflare.com/`
需要严格 204 状态码	`http://www.gstatic.com/generate_204`（境外）
全球通用，兼容性佳	`http://cp.cloudflare.com/`

体验评分仅为粗略延迟测试，大概率与实际不符，仅作参考。

Remnawave 节点管理面板：落地篇

Thu, 23 Oct 2025 18:57:09 GMT

:::info 落地篇是指在Remna节点管理面板中配置落地节点，用于转发流量。 :::

搭建落地节点

本人习惯使用3xui搭建落地节点

新建socks5入站

入站协议：socks
监听端口：9999 #随机即可
密码：开启
用户名：testuser
密码：testpwd

快捷获取出站配置

左侧导航栏 Xray设置->出站规则->添加出站 ，这里就有老铁问了，我落地鸡添加什么出站？其实是利用3xui的工具来获取配置参数，不用快捷工具徒手搓这简直唐的没边了！填入刚刚新建的socks5入站配置参数点击 JSON选项卡，复制出配置参数

{
  "tag": "落地鸡",
  "protocol": "socks",
  "settings": {
    "servers": [
      {
        "address": "落地鸡IP",
        "port": 9999,
        "users": [
          {
            "user": "testuser",
            "pass": "testpwd"
          }
        ]
      }
    ]
  }
}

这里算是完成落地鸡的配置，后面就可以在Remna节点管理面板中配置中转节点了。

修改Remna节点配置

先进入Xray设置

{
  "log": {
    "loglevel": "info"
  },
  "inbounds": [
    {
      "tag": "test1",
      "port": 30004,
      "protocol": "vless",
      "settings": {
        "clients": [],
        "decryption": "none"
      },
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls",
          "quic"
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "dest": "www.amd.com:443",
          "show": false,
          "xver": 0,
          "spiderX": "",
          "shortIds": [
            "42aeec",
            "66c8bd6b1002427d",
            "5a1f",
            "6c",
            "adfb6126",
            "ce557a621e",
            "5fc062b8b4c2b9",
            "e4cfaf01e274"
          ],
          "publicKey": "3FB5YuwJgxCbQurerSwjhXDIHAB_SRdyecd5XLhtwE0",
          "privateKey": "m5mIb4EXjqkcfDDHRW_pU7Vz-hehwNgR5Hi2HFCO4S0",
          "serverNames": [
            "www.amd.com"
          ]
        }
      }
    }
  ],
  "outbounds": [
    {
      "tag": "落地鸡",
      "protocol": "socks",
      "settings": {
        "servers": [
          {
            "address": "落地鸡IP",
            "port": 9999,
            "users": [
              {
                "user": "testuser",
                "pass": "testpwd"
              }
            ]
          }
        ]
      }
    },
    {
      "tag": "DIRECT",
      "protocol": "freedom"
    },
    {
      "tag": "BLOCK",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": [
          "test1",
        ],
        "outboundTag": "落地鸡"
      },
      {
        "ip": [
          "geoip:private"
        ],
        "type": "field",
        "outboundTag": "BLOCK"
      },
      {
        "type": "field",
        "domain": [
          "geosite:private"
        ],
        "outboundTag": "BLOCK"
      },
      {
        "type": "field",
        "protocol": [
          "bittorrent"
        ],
        "outboundTag": "BLOCK"
      }
    ]
  }
}

点击下方保存，开始奔放吧！

Remnawave 节点管理面板：面板篇

Sat, 18 Oct 2025 21:37:53 GMT

:::tip Remnawave 是一款功能强大的节点管理面板，可以帮助你管理节点状态、配置、订阅和用户等。 :::

面板官网：https://remna.st/

安装 Docker

如果尚未安装 Docker，使用官方脚本一键安装：

sudo curl -fsSL https://get.docker.com | sh

第一步 - 下载所需文件

创建项目目录：

mkdir /opt/remnawave && cd /opt/remnawave

下载 docker-compose.yml 文件：

curl -o docker-compose.yml https://raw.githubusercontent.com/remnawave/backend/refs/heads/main/docker-compose-prod.yml

下载 .env 文件：

curl -o .env https://raw.githubusercontent.com/remnawave/backend/refs/heads/main/.env.sample

第二步 - 配置 .env 文件

生成安全密钥

JWT_AUTH_SECRET 和 JWT_API_TOKENS_SECRET 用于身份验证和相关安全功能，运行以下命令自动生成：

sed -i "s/^JWT_AUTH_SECRET=.*/JWT_AUTH_SECRET=$(openssl rand -hex 64)/" .env && sed -i "s/^JWT_API_TOKENS_SECRET=.*/JWT_API_TOKENS_SECRET=$(openssl rand -hex 64)/" .env

生成随机密码

sed -i "s/^METRICS_PASS=.*/METRICS_PASS=$(openssl rand -hex 64)/" .env && sed -i "s/^WEBHOOK_SECRET_HEADER=.*/WEBHOOK_SECRET_HEADER=$(openssl rand -hex 64)/" .env

更改 Postgres 密码

强烈建议修改默认的 Postgres 密码：

pw=$(openssl rand -hex 24) && sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$pw/" .env && sed -i "s|^\(DATABASE_URL=\"postgresql://postgres:\)[^\@]*\(@.*\)|\1$pw\2|" .env

配置域名

打开 .env 文件，更新以下两个变量：

FRONT_END_DOMAIN：面板的访问域名。例：panel.yourdomain.com
SUB_PUBLIC_DOMAIN：订阅地址，在面板域名后加上 /api/sub。例：panel.yourdomain.com/api/sub

:::tip 更多环境变量的说明，请参考官方文档 - Environment Variables。 :::

第三步 - 启动容器

docker compose up -d && docker compose logs -f -t

启动后稍等片刻，日志输出正常即表示面板已成功运行。

下一步 - 配置反向代理

:::danger 必须配置反向代理才能正常使用 Remnawave 面板。

请勿将服务直接暴露到公网，Remnawave 各服务应仅绑定到 127.0.0.1。 :::

建议使用 1Panel 或 Nginx Proxy Manager 管理反向代理，将 panel.yourdomain.com 反向代理到本机 3000 端口。

Remnawave 节点管理面板：节点篇

Sat, 18 Oct 2025 17:16:41 GMT

:::note Remnawave Panel 不包含 Xray-core，因此需要在单独的服务器上安装 Remnawave Node 才能使用完整功能。节点端同样需要先安装 Docker。 :::

第一步 - 创建项目目录

mkdir /opt/remnanode && cd /opt/remnanode

第二步 - 在面板添加节点

进入面板的 节点 → 管理，点击 + 按钮添加新节点。

填写表单时注意 Node Port 字段，这是节点监听面板内部 API 请求的端口，不用于其他用途。

填好后点击 复制 docker-compose.yml 按钮，将配置复制到剪贴板。

第三步 - 创建 docker-compose.yml 文件

nano /opt/remnanode/docker-compose.yml

将从面板复制的内容粘贴进去，生成的文件格式如下：

services:
    remnanode:
        container_name: remnanode
        hostname: remnanode
        image: remnawave/node:latest
        restart: always
        network_mode: host
        environment:
          - NODE_PORT=2222
          - SECRET_KEY="supersecretkey"

保存文件后启动容器：

第四步 - 启动节点容器

docker compose up -d && docker compose logs -f -t

第五步 - 完成节点关联

回到面板的节点创建卡片，点击 下一步，选择所需的配置文件（Config Profile），然后点击 创建 按钮完成关联。

:::danger 防火墙安全提示 请务必在节点防火墙中将 NODE_PORT 仅对面板服务器的 IP 开放，不要对公网开放此端口。 :::

编辑 Xray 配置文件

vless+tcp+reality配置

想图方便可以直接复制粘贴进配置文件，入站标签是唯一的可以自定义

{
  "log": {
    "loglevel": "info"
  },
  "inbounds": [
    {
      "tag": "test1",
      "port": 30004,
      "protocol": "vless",
      "settings": {
        "clients": [],
        "decryption": "none"
      },
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls",
          "quic"
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "dest": "www.amd.com:443",
          "show": false,
          "xver": 0,
          "spiderX": "",
          "shortIds": [
            "42aeec",
            "66c8bd6b1002427d",
            "5a1f",
            "6c",
            "adfb6126",
            "ce557a621e",
            "5fc062b8b4c2b9",
            "e4cfaf01e274"
          ],
          "publicKey": "3FB5YuwJgxCbQurerSwjhXDIHAB_SRdyecd5XLhtwE0",
          "privateKey": "m5mIb4EXjqkcfDDHRW_pU7Vz-hehwNgR5Hi2HFCO4S0",
          "serverNames": [
            "www.amd.com"
          ]
        }
      }
    }
  ],
  "outbounds": [
    {
      "tag": "DIRECT",
      "protocol": "freedom"
    },
    {
      "tag": "BLOCK",
      "protocol": "blackhole"
    }
  ],
  "routing": {
    "rules": [
      {
        "ip": [
          "geoip:private"
        ],
        "type": "field",
        "outboundTag": "BLOCK"
      },
      {
        "type": "field",
        "domain": [
          "geosite:private"
        ],
        "outboundTag": "BLOCK"
      },
      {
        "type": "field",
        "protocol": [
          "bittorrent"
        ],
        "outboundTag": "BLOCK"
      }
    ]
  }
}

publicKey和privateKey,可以在下方工具栏生成

将配置文件与节点关联

如果需要更换已关联的配置文件，可在 节点 → 管理 中选中对应节点，点击更改配置文件，重新选择 Xray 配置文件和入站标签，点击应用更改后保存。

完成配置文件关联后，节点仍无法直接使用，还需要继续创建主机。

创建主机

在这就是将入站真正的开启并监听端口选择主机 → 创建主机备注自定义，选择入站配置文件为刚刚创建的test1，点击应用更改可以看到端口自动填入了30004，地址要填绑定了节点的IP的域名，将右上角按钮到开启状态，至此可以看到入站为如下状态

最后一步

完成以上的步骤是99%，剩下1%是将配置文件赋予给用户。进入内部分组，编辑默认分组文件，将配置文件赋予给分组，点击应用更改，再点击保存。

现在可以再用户列表选中用户，看到订阅链接。

此面板玩法极其丰富，适合几个人合租使用。

Fuwari 主题：集成 Giscus 评论区

Wed, 08 Oct 2025 00:00:00 GMT

giscus简介

giscus 加载时，会使用 GitHub Discussions 搜索 API 根据选定的映射方式（如 URL、pathname、<title> 等）来查找与当前页面关联的 discussion。如果找不到匹配的 discussion，giscus bot 就会在第一次有人留下评论或回应时自动创建一个 discussion。

配置Github

该仓库是公开的，否则访客将无法查看 discussion。
giscus app 已安装，否则访客将无法评论和回应。
Discussions 功能已在你的仓库中启用。

配置giscus

打开giscus官网，填入仓库地址，选择 Discussion 分类和映射方式后，页面会自动生成配置脚本。其中 data-repo-id 和 data-category-id 是 giscus 根据你填写的仓库和分类自动生成的唯一标识，直接复制即可。

<script src="https://giscus.app/client.js"
        data-repo="Ham0mer/giscus-fuwari"
        data-repo-id="R_kgDOP-iBJw"
        data-category="Announcements"
        data-category-id="DIC_kwDOP-iBJ84CwZLW"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="zh-CN"
        crossorigin="anonymous"
        async>
</script>

创建/修改fuwari文件

创建GiscusComment

在 src/components/misc/ 目录下创建 GiscusComment.astro。该组件接收 repo、repoId、category、categoryId 等参数，动态加载 giscus 脚本，并监听主题变化自动切换 giscus 的亮/暗主题。

组件代码可参考项目仓库中的 GiscusComment.astro，核心逻辑：

根据页面 dark class 判断当前主题色，传给 giscus
通过 MutationObserver 监听主题切换，用 postMessage 通知 giscus iframe 更新主题

引入到文章页面

编辑 src/pages/posts/[...slug].astro，在文件头部引入组件：

import GiscusComment from "../../components/misc/GiscusComment.astro";

在文章内容下方（License 之后、上一篇/下一篇导航之前）放入评论区：

<GiscusComment
    repo="Ham0mer/giscus-fuwari"
    repoId="R_kgDOP-iBJw"
    category="Announcements"
    categoryId="DIC_kwDOP-iBJ84CwZLW"
/>

repoId 和 categoryId 即上一步 giscus 官网生成的对应值，替换为你自己的即可。

Steam Web API：简易使用介绍

Tue, 07 Oct 2025 00:00:00 GMT

最近想更新关于页面的 Steam 展示组件，记录一下 Steam Web API 的使用方法。官方文档地址：steamcommunity.com/dev，第三方可视化文档：steamapi.xpaw.me

准备工作

1. 申请 API Key

打开 Steam API Key 申请页面，登录后填写域名（随意填写，如 localhost），即可获得密钥。下文用 XXXXXX 代替。

:::warning API Key 是私密凭证，请勿公开或提交到代码仓库。 :::

2. 查询 SteamID64

Steam 使用 64 位 ID 唯一标识用户，有以下几种方式查询：

SteamDB 计算器：用 Steam 账号登录或输入社区昵称查询
steamid.io：输入任意格式 Steam ID 互转
ResolveVanityURL 接口：通过自定义 URL 解析（见下文）

下文用 123456 代替 SteamID64，用 000000 代替游戏 AppID。

接口格式

Steam Web API 的统一请求格式：

https://api.steampowered.com/{interface}/{method}/v{version}/?key=XXXXXX&{params}

参数	说明
`interface`	API 分类，如 `ISteamUser`、`IPlayerService`
`method`	具体功能，如 `GetPlayerSummaries`
`version`	版本号，通常为 `v1` 或 `v2`，写 `v1` 与 `v0001` 均可
`key`	您的 API Key
`format`	可选，返回格式：`json`（默认）、`xml`、`vdf`

:::tip http 和 https 均可使用。key 参数必须传递，否则大多数接口会返回错误。 :::

查询当前 Key 可用的所有 API：

https://api.steampowered.com/ISteamWebAPIUtil/GetSupportedAPIList/v1/?key=XXXXXX

用户相关 API

用户基本信息

获取昵称、头像、在线状态、国家、创建时间等。steamids 支持逗号分隔传入多个 ID。

https://api.steampowered.com/ISteamUser/GetPlayerSummaries/v2/?key=XXXXXX&steamids=123456

自定义 URL 解析 SteamID

通过用户设置的自定义社区 URL 解析出 SteamID64：

https://api.steampowered.com/ISteamUser/ResolveVanityURL/v1/?key=XXXXXX&vanityurl=gaben

好友列表

获取好友列表及成为好友的时间（UNIX 时间戳）：

https://api.steampowered.com/ISteamUser/GetFriendList/v1/?key=XXXXXX&steamid=123456

组列表

获取用户加入的 Steam 组：

https://api.steampowered.com/ISteamUser/GetUserGroupList/v1/?key=XXXXXX&steamid=123456

封禁记录

查询 VAC 封禁、游戏封禁信息，steamids 支持多个 ID：

https://api.steampowered.com/ISteamUser/GetPlayerBans/v1/?key=XXXXXX&steamids=123456

游戏库与游玩相关 API

游戏库存

获取用户拥有的所有游戏及游玩时间。添加 include_appinfo=1 可在响应中包含游戏名称和图标：

https://api.steampowered.com/IPlayerService/GetOwnedGames/v1/?key=XXXXXX&steamid=123456&include_appinfo=1

:::tip Steam 曾清理过部分低质量游戏，这些游戏不计入用户主页的游戏总数，但此接口仍会列出。 :::

所有游戏使用时长

获取所有产品的总游玩时间，以及在 Windows/Linux/Mac 各平台的分别时长：

https://api.steampowered.com/IPlayerService/ClientGetLastPlayedTimes/v1/?key=XXXXXX

等级与徽章 API

社区等级

https://api.steampowered.com/IPlayerService/GetSteamLevel/v1/?key=XXXXXX&steamid=123456

徽章列表

获取所有已获得徽章的详情，包括徽章 ID、等级、经验值、解锁时间等：

https://api.steampowered.com/IPlayerService/GetBadges/v1/?key=XXXXXX&steamid=123456

成就相关 API

玩家成就

获取指定游戏中玩家的成就完成情况（必须指定 AppID）：

https://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v1/?key=XXXXXX&steamid=123456&appid=000000

全球成就完成率

无需 Key，获取某款游戏所有成就在全球玩家中的完成百分比：

https://api.steampowered.com/ISteamUserStats/GetGlobalAchievementPercentagesForApp/v2/?gameid=000000

游戏统计数据定义

获取游戏开发者定义的成就和统计数据结构：

https://api.steampowered.com/ISteamUserStats/GetSchemaForGame/v2/?key=XXXXXX&appid=000000

游戏信息 API

游戏新闻

获取指定游戏的最新公告，可控制数量和内容长度：

https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=000000&count=5&maxlength=500

商店详情（非官方 Store API）

获取游戏详细信息，包括简介、价格、类型、标签、系统需求、截图等（中文内容加 l=schinese）：

https://store.steampowered.com/api/appdetails?appids=000000&l=schinese

所有游戏列表

获取 Steam 商店上的所有游戏列表（AppID + 名称），数据量较大：

https://api.steampowered.com/ISteamApps/GetAppList/v2/

游戏资源

游戏头图

https://cdn.cloudflare.steamstatic.com/steam/apps/{appid}/header.jpg

游戏胶囊图（纵向）

https://cdn.cloudflare.steamstatic.com/steam/apps/{appid}/library_600x900.jpg

游戏截图

游戏截图 URL 可从 appdetails 接口的 screenshots 字段中获取。

便捷代理接口

如果不想自己管理 API Key，可使用封装好的代理接口（以下为示例站点，数据仅供参考）：

功能	接口示例
个人信息	`https://o.jk.sb/steam/profile/76561198887857717`
游戏库存	`https://o.jk.sb/steam/games/76561198887857717`
最近游玩	`https://o.jk.sb/steam/recentlyplayed/76561198887857717`
最近游玩（指定数量）	`https://o.jk.sb/steam/recentlyplayed/76561198887857717/3`
游戏成就	`https://o.jk.sb/steam/achievements/76561198887857717/275850`
游戏封面（Base64）	`https://o.jk.sb/steam/imageurl2base64/275850`

注意事项

大部分用户相关接口需要账号社区信息设为公开，否则返回数据异常或为空
不同类型的 Key（开发者 / 普通玩家）可访问的接口范围不同
API 存在速率限制，请勿频繁大量请求，否则 IP 可能被临时封禁
Steam 周年庆游玩回顾（Replay）页面：https://store.steampowered.com/replay/{steamid}/{year}

ASF + TGbot：Docker 部署指南

Sun, 05 Oct 2025 00:00:00 GMT

ArchiSteamFarm（ASF）是一个开源的 Steam 挂卡程序，支持多账号管理、Web UI 以及 Telegram Bot 控制。本文介绍如何用 Docker 快速部署 ASF 及其 Telegram 控制 Bot。

::github{repo="JustArchiNET/ArchiSteamFarm"}

安装 ASF

1. 启动容器

docker run -d \
  -p 127.0.0.1:1242:1242 \
  -v /opt/ASF/config:/app/config \
  -v /opt/ASF/plugins:/app/plugins \
  --name asf \
  --restart unless-stopped \
  --pull always \
  justarchi/archisteamfarm

:::tip 端口绑定到 127.0.0.1 而非 0.0.0.0，可防止 IPC 接口暴露到公网。 :::

2. 配置 ASF.json

在 /opt/ASF/config/ 下创建全局配置文件：

{
  "IPCPassword": "yourpassword",
  "SteamOwnerID": 76561198000000000
}

IPCPassword：访问 Web UI 所需的密码，建议设置
SteamOwnerID：您的 Steam 64位 ID，可在 steamid.io 查询

3. 配置 IPC.config

此文件让 ASF Web UI 可以在容器外访问：

{
  "Kestrel": {
    "Endpoints": {
      "HTTP": {
        "Url": "http://*:1242"
      }
    }
  }
}

4. 添加 Steam 账号

为每个 Steam 账号在 /opt/ASF/config/ 下创建一个以账号命名的 JSON 文件：

{
  "SteamLogin": "你的Steam用户名",
  "SteamPassword": "你的Steam密码",
  "Enabled": true
}

:::warning Bot 配置文件名（如 MyBot.json）即为机器人名称，请避免使用特殊字符或空格。 :::

5. 重启并访问 Web UI

docker restart asf

浏览器打开 http://localhost:1242，使用 IPCPassword 登录即可管理所有账号。

配置 2FA（可选但推荐）

若您的 Steam 账号已开启手机令牌，ASF 支持托管 2FA，登录后无需手动输入验证码，并可自动确认交易。

在 ASF Web UI 的 2FA 管理 页面，按提示导入手机令牌的 shared_secret 完成绑定。

:::caution 导入 2FA 后，请妥善保存原始密钥备份。ASF 2FA 与手机令牌并行存在，两者均可生成有效验证码。 :::

安装 TGbot

ASFBot 让您可以通过 Telegram 远程控制 ASF。

::github{repo="dmcallejo/ASFBot"}

1. 创建 Telegram Bot

前往 @BotFather，发送 /newbot 创建一个 Bot，保存返回的 Token。

2. 使用 docker-compose（推荐）

使用 docker-compose 同时管理 ASF 和 ASFBot，两个服务通过内部网络通信，无需将 IPC 端口暴露给外部：

services:
  asf:
    image: justarchi/archisteamfarm
    container_name: asf
    restart: unless-stopped
    ports:
      - "127.0.0.1:1242:1242"
    volumes:
      - ./config:/app/config
      - ./plugins:/app/plugins

  asfbot:
    image: ghcr.io/dmcallejo/asfbot
    container_name: asfbot
    restart: unless-stopped
    depends_on:
      - asf
    environment:
      - ASF_IPC_HOST=asf
      - ASF_IPC_PORT=1242
      - ASF_IPC_PASSWORD=yourpassword
      - TELEGRAM_BOT_TOKEN=你的Bot_Token
      - TELEGRAM_USER_ALIAS=@你的Telegram用户名
      # 国内服务器可取消注释以下代理配置
      # - TELEGRAM_PROXY=http://代理IP:代理端口

docker compose up -d

:::tip 使用 docker-compose 时，ASF_IPC_HOST 填写 asf（服务名），两个容器在同一网络内直接通信，无需 --network host。 :::

3. 单独运行 ASFBot

如果 ASF 已单独运行，可用以下命令单独启动 ASFBot：

docker run -d \
  --name asfbot \
  --restart unless-stopped \
  --network host \
  -e ASF_IPC_HOST=127.0.0.1 \
  -e ASF_IPC_PORT=1242 \
  -e ASF_IPC_PASSWORD=yourpassword \
  -e TELEGRAM_BOT_TOKEN=你的Bot_Token \
  -e TELEGRAM_USER_ALIAS=@你的Telegram用户名 \
  ghcr.io/dmcallejo/asfbot

国内服务器可添加 -e TELEGRAM_PROXY=http://代理IP:代理端口 通过代理连接 Telegram。

4. 常用 Bot 命令

向您的 Bot 发送以下命令来控制 ASF：

命令	说明
`/status`	查看所有 Bot 运行状态
`/start BotName`	启动指定 Bot
`/stop BotName`	停止指定 Bot
`/pause BotName`	暂停挂卡
`/resume BotName`	恢复挂卡
`/farm BotName`	手动触发挂卡
`/2fa BotName`	获取当前 2FA 令牌
`/help`	查看全部可用命令

Maddy：自建邮件服务器指南

Sat, 06 Sep 2025 00:00:00 GMT

maddy 是一个开箱即用的一体化邮件服务器，集 MTA、IMAP、DKIM、SPF、DMARC 于一身，配置比传统 Postfix + Dovecot 方案简单很多。

::github{repo="foxcpp/maddy"}

前置条件

一台有独立公网 IP 的 VPS（需要开放 25、587、993、143 端口，部分云厂商默认封禁 25 端口，需提工单申请）
一个已解析的域名（例如 example.com）
一个指向服务器 IP 的子域名作为邮件主机名（例如 mx.example.com）
SSL/TLS 证书（推荐 Let's Encrypt，可用 acme.sh 或 Certbot 申请）

:::warning 请先确认您的 VPS 已开放 TCP 25 端口，否则无法收发外部邮件。阿里云、腾讯云等默认封禁，需单独申请。 :::

安装 maddy

使用 docker-compose（推荐）

services:
  maddy:
    image: foxcpp/maddy:latest
    container_name: maddy
    restart: unless-stopped
    ports:
      - "25:25"       # SMTP (接收外部邮件)
      - "587:587"     # SMTP Submission (客户端发信)
      - "143:143"     # IMAP
      - "993:993"     # IMAPS (TLS)
    environment:
      - MADDY_HOSTNAME=mx.example.com   # 邮件服务器主机名
      - MADDY_DOMAIN=example.com        # 处理的邮件域名
    volumes:
      - ./maddy-data:/data

docker compose up -d

:::tip /data 目录会自动生成默认配置文件 maddy.conf，以及 DKIM 私钥等数据。需要自定义配置时，直接编辑 ./maddy-data/maddy.conf 后重启容器。 :::

配置 TLS 证书

maddy 首次启动会因找不到证书而失败。将证书文件复制到数据目录：

cp /path/to/fullchain.pem ./maddy-data/tls/fullchain.pem
cp /path/to/privkey.pem   ./maddy-data/tls/privkey.pem

然后重启容器：

docker compose restart maddy

DNS 配置

以下记录均以 example.com 为例，请替换为您的实际域名。

基础记录

类型	主机记录	值
A	`mx`	服务器公网 IP
MX	`@`	`mx.example.com`（优先级 10）
PTR	服务器 IP	`mx.example.com`（在 VPS 管理面板设置反向解析）

:::important PTR 反向解析（rDNS）是许多邮件服务器判断是否接收邮件的重要依据，务必配置，否则发出的邮件极易进垃圾箱。 :::

SPF 记录

v=spf1 mx ~all

类型	主机记录	值
TXT	`@`	`v=spf1 mx ~all`

DKIM 记录

maddy 在首次启动后会自动生成 DKIM 密钥，查看公钥内容：

cat ./maddy-data/dkim_keys/example.com_default.dns

输出示例（格式为 DNS TXT 记录值）：

v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

将该内容添加到 DNS：

类型	主机记录	值
TXT	`default._domainkey`	上方输出的完整内容

DMARC 记录

v=DMARC1; p=quarantine; rua=mailto:postmaster@example.com

类型	主机记录	值
TXT	`_dmarc`	`v=DMARC1; p=quarantine; rua=mailto:postmaster@example.com`

:::tip DNS 记录生效通常需要几分钟到数小时，配置完成后可使用 mail-tester.com 检测评分，7 分以上为合格。 :::

账户管理

以下命令均在容器内执行，先进入容器终端：

docker exec -it maddy sh

创建邮箱账户

创建登录凭证（执行后会提示设置密码）：

maddy creds create admin@example.com

创建 IMAP 存储账户：

maddy imap-acct create admin@example.com

:::important 两步都要执行：creds create 负责认证登录，imap-acct create 负责创建邮件存储。缺少任意一步，账户都无法正常使用。 :::

修改密码

maddy creds password admin@example.com

查看账户列表

maddy creds list
maddy imap-acct list

管理邮箱文件夹

查看账户下的邮箱分类：

maddy imap-mboxes list admin@example.com

测试收发邮件

测试收信

使用 QQ 邮箱、Gmail 等向 admin@example.com 发送一封测试邮件，然后在容器内查看收件箱：

maddy imap-msgs list admin@example.com INBOX

测试发信评分

使用邮件客户端（Thunderbird、Apple Mail 等）通过以下参数连接后发送测试邮件到 mail-tester.com：

参数	值
IMAP 服务器	`mx.example.com`
IMAP 端口	`993`（SSL/TLS）
SMTP 服务器	`mx.example.com`
SMTP 端口	`587`（STARTTLS）
用户名	`admin@example.com`

常见问题

邮件进了垃圾箱？ 检查 PTR 反向解析是否配置、DKIM/SPF/DMARC 是否全部生效，可在 MXToolbox 逐项验证。

25 端口被封？ 联系 VPS 服务商提工单解封，或换用不封 25 端口的服务商（如 Vultr、Hetzner）。

日志查看：

docker logs -f maddy

Seedbox：一键安装与 PT 刷流指南

Sat, 06 Sep 2025 00:00:00 GMT

Seedbox 是专用于 PT（私有 Tracker）下载和做种的服务器环境。本文介绍如何使用 jerry048 的一键脚本快速搭建，并说明各组件的用途与进阶优化方法。

::github{repo="jerry048/Dedicated-Seedbox"}

一键安装

bash <(wget -qO- https://raw.githubusercontent.com/jerry048/Dedicated-Seedbox/main/Install.sh) \
  -u <用户名> \
  -p <密码> \
  -c <缓存大小(MiB)> \
  -q <qBittorrent 版本> \
  -l <libtorrent 版本> \
  [选项...]

参数说明

参数	说明
`-u`	系统用户名
`-p`	用户密码
`-c`	qBittorrent 缓存大小（单位 MiB，建议为内存的 1/4）
`-q`	qBittorrent 版本号，如 `4.3.9`
`-l`	libtorrent 版本号，如 `v1.2.19`
`-b`	安装 autobrr（国际 PT 自动抢种）
`-v`	安装 Vertex（综合刷流管理工具）
`-r`	安装 autoremove-torrents（自动删种）
`-3`	启用 BBR V3 网络加速
`-x`	启用 BBRx 网络加速
`-o`	自定义端口

安装示例

bash <(wget -qO- https://raw.githubusercontent.com/jerry048/Dedicated-Seedbox/main/Install.sh) \
  -u jerry048 \
  -p 1LDw39VOgors \
  -c 3072 \
  -q 4.3.9 \
  -l v1.2.19 \
  -v -x

此命令安装 qBittorrent 4.3.9（libtorrent v1.2.19），缓存 3 GB，安装 Vertex，启用 BBRx 加速。

支持的系统与架构

类别	支持范围
操作系统	Debian 10+、Ubuntu 20.04+
CPU 架构	x86_64、ARM64

工具介绍

qBittorrent

主力下载/做种客户端，支持 Web UI 远程管理，是 PT 刷流的核心程序。

autobrr — 国际 PT 自动抢种

::github{repo="autobrr/autobrr"}

autobrr 通过监听 PT 站的 IRC #announce 频道，在种子发布的第一时间自动推送到下载客户端，适合国际 PT 站（如 BTN、PTP、RED 等）的抢首发场景。

Vertex — 综合刷流管理工具

::github{repo="vertex-app/vertex"}

Vertex 是面向 PT 玩家的一体化管理工具，支持：

RSS 自动订阅与推送下载
按规则自动删除低效种子
多下载器负载均衡
追剧与刷流一体化流程

:::tip Vertex 官方文档：wiki.vertex.icu :::

autoremove-torrents — 自动删种

::github{repo="jerrym19881225/autoremove-torrents"}

根据自定义规则（分享率、做种时间、种子大小等）自动清理低效种子，释放磁盘和带宽资源，支持 qBittorrent、Transmission、Deluge 等客户端。

网络加速：BBR V3 与 BBRx

BBR（Bottleneck Bandwidth and Round-trip propagation time）是 Google 开发的 TCP 拥塞控制算法，相比传统 CUBIC 算法在高带宽、长延迟或轻微丢包网络环境下有明显优势。

选项	说明
BBR V3（`-3`）	Google 官方最新版，已提交 Linux 内核主线，稳定性好
BBRx（`-x`）	社区魔改版，激进调优，适合带宽充裕的 Seedbox 场景

:::tip 一般 Seedbox 推荐 BBRx；对稳定性有要求的生产环境选 BBR V3。两者互斥，只能选一个。 :::

进阶优化备注

缓存大小

缓存建议设为机器内存的 1/4。如使用 qBittorrent 4.3.x，受内存溢出问题影响，应保守设置在 1/8。

异步 I/O 线程数

默认值为 4，对 HDD 友好。若使用 SSD 或 NVMe，可调整为 8～16：

qBittorrent 4.3.x：高级选项中直接修改
qBittorrent 4.1.x：在 /home/$username/.config/qBittorrent/qBittorrent.conf 的 [BitTorrent] 段添加：
```
Session\AsyncIOThreadsCount=8
```
修改前请先关闭 qBittorrent。
Deluge：通过 ltconfig 插件设置 aio_threads=8

发送缓冲区（I/O 较差的机器）

对于磁盘 I/O 较弱的机器，适当降低以下参数：

qBittorrent 4.3.x：高级选项中修改

qBittorrent 4.1.x：在配置文件 [BitTorrent] 段添加：

Session\SendBufferWatermark=5120
Session\SendBufferLowWatermark=1024
Session\SendBufferWatermarkFactor=150

Deluge（ltconfig）：

send_buffer_low_watermark=1048576
send_buffer_watermark=5242880
send_buffer_watermark_factor=150

tick_interval（CPU 较差的机器）

调高 tick_interval 可节省 CPU 资源（qBittorrent 暂不支持此项）：

Deluge（ltconfig）：tick_interval=250

TCP 缓存大小

/etc/sysctl.conf 中配置的 TCP 缓存对低端机器可能偏大，请根据实际情况酌情调低。

文件系统

强烈推荐使用 XFS 文件系统，在多并发做种场景下 I/O 性能优于 ext4。

业余玩家

Fuwari 主题：添加文章置顶功能

修改工具文件

修改排序逻辑（一）

修改排序逻辑（二）

修改文章配置文件

修改置顶显示标签

第一处：添加置顶标签判断

第二处：添加置顶标签显示

Linux 网络排查：TIME_WAIT、偶发丢包与 MTU 黑洞的内核调优实战

故事：从一个"假死"的服务说起

坑一：TIME_WAIT 堆积导致服务"假死"

现象

原理速记

排查命令

调优

坑二：偶发丢包——监控显示 0%，但用户在喊延迟

第 1 步：先看网卡层有没有丢

第 2 步：协议栈是不是在丢

第 3 步：conntrack 表满

第 4 步：抓包确认

第 5 步：内核层面看丢包点

坑三：MTU 黑洞——能 ping 通但传文件卡死

原理

排查

修复

内核参数调优清单

常用排查命令速查

总结

Claude Code 对接 DeepSeek V4 Pro：完整配置指南

1. Claude Code CLI 对接 DeepSeek V4 Pro

1.1 安装 Claude Code

1.2 配置环境变量

1.3 环境变量说明

1.4 模型选择

1.5 启动使用

2. VSCode 插件对接 DeepSeek V4 Pro

2.1 安装插件

2.2 配置 settings.json

2.3 切换模型

2.4 验证配置

注意事项

CPA Usage Keeper：CLIProxyAPI 用量追踪与可视化面板

核心概念

功能特性

前置条件

安装部署

方式一：Docker Compose（推荐）

方式二：Docker（CPA 已在宿主机运行）

方式三：Linux 二进制

systemd 常驻运行

配置详解

最小必填

Web 访问与反代

登录保护

时区与请求

Redis 队列高级配置

存储、日志与备份

内置 HTTPS

Dashboard 功能导览

总览页面

用量明细

分析页面

API Key 独立查询

凭证页面

模型价格管理

Nginx 反向代理

数据说明

常见问题

启动后 Dashboard 没有数据？

CPA 和 Keeper 的网络不通？

如何备份数据？

数据库文件越来越大？

登录密码忘了？

子路径部署后页面白屏？

安全建议

相关项目

DeepSeek-TUI：终端原生 AI 编程智能体

核心特性

安装