Junyi's Lab

用 nerdctl + Tailscale Sidecar 让容器流量走 Exit Node：踩坑全记录

junyi.h@comp.nus.edu.sg (Junyi Hou) — Fri, 06 Mar 2026 00:00:00 +0800

在容器化部署中，有时候我们需要让容器的所有出站流量通过特定的网络出口。Tailscale 的 sidecar 模式可以做到这一点：用一个 Tailscale 容器作为 sidecar，其他容器共享它的网络命名空间，流量通过 WireGuard 隧道经由远端 exit node 出去。

这个方案在 Docker Compose 下很成熟，但迁移到 nerdctl（containerd）时，我踩了一连串的坑。记录下来，希望能帮后来人少走弯路。

# 最终目标

让任意容器通过 Tailscale sidecar 接入 tailnet，所有出站流量经由远程 exit node 转发。架构如下：

为了方便验证网络是否通畅，我用 nicolaka/netshoot 作为测试容器——它自带 curl、dig、tcpdump、iperf 等一整套网络排查工具，比临时装工具方便得多。

# 坑 1：nerdctl compose 不支持 `network_mode: service:xxx`

Docker Compose 支持 network_mode: service:<service_name> 语法，它会自动把 service 名解析为对应容器的网络命名空间。但 nerdctl compose 没有实现这个翻译层，直接报错：

unsupported network_mode: service:tailscale-sidecar

解法： 改用 network_mode: container:<container_name>，并通过 container_name 字段固定 sidecar 容器的名称。

services:
 tailscale-sidecar:
 container_name: tailscale-sidecar # 固定名称
 # ...
 netshoot:
 network_mode: container:tailscale-sidecar # 用容器名而非服务名

如果不固定 container_name，nerdctl compose 会自动生成类似 blockchain-tailscale-sidecar-1 的名称，导致引用不匹配。

# 坑 2：Tailscale ACL 中未定义 tag

启动后 Tailscale 容器立即退出，日志显示：

Received error: requested tags [tag:container] are invalid or not permitted

解法： 在 Tailscale 管理后台的 ACL 策略中添加 tag 定义，并在生成 auth key 时勾选对应 tag：

"tagOwners": {
 "tag:container": ["autogroup:admin"]
}

# 坑 3：缺少 `SYS_MODULE` capability

这个坑最隐蔽。容器能正常加入 tailnet，tailscale ping 也通，但开启 exit node 后 TCP 流量完全不通，只有 ICMP 能过。

原因是内核模式（TS_USERSPACE=false）需要加载 xt_mark、nf_nat 等内核模块来设置 iptables 转发规则。缺少 SYS_MODULE capability 时，这些模块无法加载，iptables 规则写入但不生效，表现为 ICMP 正常而 TCP 断流。

解法：

cap_add:
 - net_admin
 - SYS_MODULE # 必须加上

# 坑 4：Exit Node 模式下 DNS 失败

开启 exit node 后，容器所有出站流量都走 WireGuard 隧道到远端 exit node 再出去。但 /etc/resolv.conf 里的 DNS 服务器仍然是本地地址（如 10.0.2.3），这些地址从 exit node 那端是不可达的，DNS 查询自然失败。

症状是 curl ifconfig.me 报 Could not resolve host，而直接用 IP 访问则卡住或返回异常。

解法： 让 Tailscale 接管 DNS，查询也走隧道：

environment:
 - TS_ACCEPT_DNS=true

# 最终可用的 compose.yaml

services:
 tailscale-sidecar:
 image: tailscale/tailscale:latest
 container_name: tailscale-sidecar
 hostname: tailscale-sidecar
 environment:
 - TS_AUTHKEY=${TS_AUTHKEY}
 - TS_EXTRA_ARGS=--advertise-tags=tag:container --exit-node=${TS_EXITNODE}
 - TS_STATE_DIR=/var/lib/tailscale
 - TS_USERSPACE=false
 - TS_ACCEPT_DNS=true
 volumes:
 - ${PWD}/tailscale-sidecar/state:/var/lib/tailscale
 devices:
 - /dev/net/tun:/dev/net/tun
 cap_add:
 - net_admin
 - SYS_MODULE
 restart: unless-stopped

 netshoot:
 image: nicolaka/netshoot
 depends_on:
 - tailscale-sidecar
 network_mode: container:tailscale-sidecar
 command: sleep infinity

需要在同目录下准备 .env 文件：

TS_AUTHKEY=tskey-auth-xxxxx
TS_EXITNODE=100.x.x.x

# 验证方法

nicolaka/netshoot 自带丰富的网络工具，非常适合验证：

# 检查出口 IP，确认流量是否走了 exit node
nerdctl exec -it netshoot curl ifconfig.me

# DNS 解析测试
nerdctl exec -it netshoot dig google.com

# 查看路由表
nerdctl exec -it netshoot ip route show table all

# 抓包排查
nerdctl exec -it netshoot tcpdump -i any -n

# Tailscale 侧的状态检查
nerdctl exec -it tailscale-sidecar tailscale status
nerdctl exec -it tailscale-sidecar tailscale exit-node status
nerdctl exec -it tailscale-sidecar tailscale ping <exit-node-ip>

# 排查思路总结

这次排查的过程本身也值得回顾。面对"exit node 不工作"这样的复合问题，有效的方法是逐层剥离：

先确认隧道连通性： tailscale ping 验证 WireGuard 隧道本身是否通。
对比实验： 关掉 exit node 测试，确认问题出在 exit node 还是基础网络。
区分协议： ICMP 通但 TCP 不通，指向 iptables/内核模块问题。
区分 DNS 和连通性： 用 IP 直连绕过 DNS，分别定位。
对比已知可用的配置： 发现之前能用的命令多了 SYS_MODULE，一下锁定问题。

每一步缩小范围，避免在错误的方向上浪费时间。

# 写在最后

nerdctl compose 作为 Docker Compose 的替代方案已经很成熟了，但在细节兼容性上仍有差距。network_mode: service: 的缺失、容器名的自动生成规则不同，这些都是迁移时容易踩到的坑。而 Tailscale 在容器中使用 exit node 时，SYS_MODULE 和 TS_ACCEPT_DNS 是两个容易被忽略但又不可或缺的配置。希望这篇记录能帮到遇到同样问题的人。

容器化、开箱即用的 VSCode + TeX 环境：告别配置烦恼，专注写作本身

junyi.h@comp.nus.edu.sg (Junyi Hou) — Tue, 23 Sep 2025 13:02:12 +0800

这篇文章为「有洁癖的程序员」和「不想折腾环境的写作者」，提供一套开箱即用的容器化 LaTeX 方案：用容器隔离环境，用 Git 同步项目，做到「拉仓库 → 打开容器 → 立即编译」，彻底告别环境配置焦虑。

你可以随时随地使用 Git 同步你的项目，随用随走，无需担心环境问题。同时，你也可以放心大胆地让 Claude Code、Codex 帮你写 LaTeX 代码，不担心执行危险指令（请做好 git push protect）

# 你只需要准备 1 件事

无需安装复杂的 TeX 发行版、不用配置系统环境变量，唯一要做的就是：

在 Cursor 或 VSCode 中，安装官方扩展 Dev Containers

Cursor 中的 Dev Container

VS Code 中的 Dev Container

# 三个步骤，从 0 到能写 LaTeX

假设你已有一个 LaTeX 项目文件夹（新建空文件夹也可以），跟着做就能用：

## Step 1 引入 Dev Container 配置

打开项目的终端（VSCode/Cursor 内置终端即可），执行以下命令，将预配置好的容器环境作为「子模块」引入项目（子模块不干扰主项目文件，方便后续更新）：

git submodule add https://github.com/paperdebugger-bot/latex-devcontainer.git .devcontainer

如果你的项目还没初始化 Git（git init），也可以直接下载配置文件解压到 .devcontainer 文件夹：latex-devcontainer.zip

## Step 2 重载编辑器窗口

按下快捷键 Ctrl + Shift + P（macOS 是 ⌘ + ⇧ + P），在弹出的命令面板中输入 Reload Window 并执行，让编辑器识别新添加的容器配置。

## Step 3 启动容器并使用

重载后，编辑器会自动弹出提示「是否在 Dev Container 中打开项目」，点击 Reopen in Container；

接下来会让你选择容器版本，直接选 full 即可 —— 等待 3-5 分钟（首次构建需下载镜像，后续会快很多），环境就搭建完成了！

🎉 完成后你会获得什么？

预装 TeX Live Full 发行版（几乎包含所有宏包，不用手动装）；
自带 LaTeX Workshop 插件（VSCode 最好用的 LaTeX 插件，支持实时预览、一键编译）¹；
配置好的 PDF 预览 功能；
干净的终端环境（可直接用 pdflatex xelatex 等命令）。

# 进阶选择：不同的容器版本怎么挑？

上面推荐的 full 版本是「省事优先」，但如果你的项目轻量化、或想节省磁盘空间，可以选其他版本。核心区别在于「预装的 TeX 发行版」不同：

容器版本	核心 TeX 发行版	特点	适合场景
full	TeX Live Full	预装所有宏包（约 6GB），编译任何项目都不会缺包	复杂论文、自定义模板、不想处理宏包问题
tiny	TinyTeX²	轻量版（约 1GB），默认含 200+ 常用宏包	简单报告、常规学术论文（缺包时需手动 `tlmgr install 宏包名`）
nano	Tectonic³	零配置引擎，自动处理依赖	快速写 Demo、极简文档（兼容性略弱，复杂宏包可能不支持）

💡 切换方法：
在启动容器时，选择对应版本即可；如果已启动容器，可通过 Ctrl + Shift + P → Dev Containers: Rebuild Container 重新选择版本。

# 为什么推荐用 Dev Container⁴？

很多人会问：「我直接在本地装 TeX Live 不行吗？」

当然可以，但 Dev Container 解决了 3 个核心痛点：

痛点 1：环境隔离，不污染系统

容器是独立的「沙盒」，所有 TeX 依赖、插件都装在容器里，不会修改你本地的系统配置（比如不会和 Python、Java 等环境冲突）。想删除环境？直接删除容器即可，不留任何残留。

痛点 2：跨设备同步，随用随走

把项目和 .devcontainer 文件夹一起用 Git 管理，换电脑时只需「拉取仓库 → 打开容器」，10 分钟内就能恢复一模一样的写作环境——再也不用在公司电脑配一次、家里电脑又配一次。

痛点 3：安全可控，放心用 AI 辅助

现在很多人用 Claude Code、Codex 生成 LaTeX 代码，这些工具可能会输出 sudo 等危险命令。而容器内的操作不会影响本地系统，相当于加了一层「安全防护」（注意：仍需做好 Git 提交保护，避免泄露敏感内容）。

# 常见问题 Q&A

Q1：构建容器时速度很慢？

A1： 首次构建需下载大镜像，建议换国内 Docker 镜像源（比如阿里云、网易云镜像），或在网络较好的环境下操作。

Q2：编译中文文档乱码？

A2： full 和 tiny 版本已预装 xeCJK 宏包，编译时选择 xelatex 引擎即可（LaTeX Workshop 已默认配置）。

Q3：如何更新容器配置？

A3： 如果远程仓库的 latex-devcontainer 有更新，可在项目终端执行：

git pull --recurse-submodules
git submodule update --recursive --remote

然后重建容器（Rebuild Container）即可应用更新。

这套方案我自己用了半年，从写技术报告到学术论文，没再遇到过一次「环境报错」。如果你也厌倦了配置 LaTeX 环境，不妨试试。

LaTeX Workshop 插件文档：掌握更多编译、预览技巧 ↩︎
TinyTeX 官方网站：轻量 TeX 发行版的使用指南 ↩︎
基于 tinytex 的中文本地 TeX 环境：如何配置 tinytex 环境 ↩︎
Dev Containers 官方文档：了解容器配置的更多细节 ↩︎

树莓派 5 集群配置 k3s

junyi.h@comp.nus.edu.sg (Junyi Hou) — Wed, 25 Dec 2024 13:07:09 +0800

K3s 是由 Rancher Labs 开发的轻量级 Kubernetes 发行版，专为资源受限的环境和边缘计算场景设计。

本文将介绍如何在 Raspberry Pi 5 集群上部署 K3s，搭建一个功能完整的容器编排平台。

# Step 1. 在 Master 和 Agent 节点分别执行命令

这部分参考了¹的 “Setting Up with k3s” 章节

## Master 节点

在 pi-1 执行

1curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
2 INSTALL_K3S_MIRROR=cn \
3 sh -s - \
4 --system-default-registry=registry.cn-hangzhou.aliyuncs.com

## Agent 节点

在 pi-2, pi-3, pi-4 执行

1curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
2 INSTALL_K3S_MIRROR=cn \
3 K3S_URL=https://100.84.216.88:6443 \
4 K3S_TOKEN=K10d0e1ccd102d3f60043941ab35d22f29ca15e0ecf48e138d502fd258ee232cb84::server:bc76905e2c32080b0c2a0501293876bd \
5 sh -s -
6
7# K3S_URL 和 K3S_TOKEN 请写你自己的
8# K3s agent 节点不需要配置 `system-default-registry`。

为什么我的 K3S_URL 是 100.84.216.88

因为我使用 tailscale ² 给树莓派集群构建了虚拟局域网。

请根据你的实际情况进行配置。

如何查看 K3S_TOKEN

cat /var/lib/rancher/k3s/server/node-token

# Step 2. 验证安装效果

# 其他：K3s 在中国大陆地区的安装

## 方法一：全新安装

³ 和 ⁴ 介绍了在安装时通过指定 INSTALL_K3S_MIRROR=cn 和 --system-default-registry 来更换 registry mirror。

1# 全新安装（master 节点）
2curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \
3 INSTALL_K3S_MIRROR=cn sh -s - \
4 --system-default-registry=registry.cn-hangzhou.aliyuncs.com

全新安装 - 命令执行结果

## 方法二：换源

这个方法适用于在国外配置好环境之后，设备迁移到中国大陆地区的无法访问默认源的用户。

我执行完 Rancher 的快速入门指南里提供的命令，发现 pods 根本没启动的

⁵

# Rancher 快速入门指南提供的代码（正常安装 k3s 但是无法启动 pod）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

卡在 ContainerCreating 步骤（黄色高亮部分）

在 /etc/systemd/system/k3s.service 里面指定 --system-default-registry，然后 systemctl daemon-reload && systemctl restart k3s 重启服务即可

 1[Unit]
 2Description=Lightweight Kubernetes
 3Documentation=https://k3s.io
 4Wants=network-online.target
 5After=network-online.target
 6
 7[Install]
 8WantedBy=multi-user.target
 9
10[Service]
11Type=notify
12EnvironmentFile=-/etc/default/%N
13EnvironmentFile=-/etc/sysconfig/%N
14EnvironmentFile=-/etc/systemd/system/k3s.service.env
15KillMode=process
16Delegate=yes
17# Having non-zero Limit*s causes performance problems due to accounting overhead
18# in the kernel. We recommend using cgroups to do container-local accounting.
19LimitNOFILE=1048576
20LimitNPROC=infinity
21LimitCORE=infinity
22TasksMax=infinity
23TimeoutStartSec=0
24Restart=always
25RestartSec=5s
26ExecStartPre=/bin/sh -xc '! /usr/bin/systemctl is-enabled --quiet nm-cloud-setup.service 2>/dev/null'
27ExecStartPre=-/sbin/modprobe br_netfilter
28ExecStartPre=-/sbin/modprobe overlay
29ExecStart=/usr/local/bin/k3s \
30 server \
31 '--system-default-registry' \
32 'registry.cn-hangzhou.aliyuncs.com' \

systemctl daemon-reload
systemctl restart k3s

k3s 正在重启服务，已经有一个服务就绪（黄色高亮）

稍等一会，全部的 Container 成功被创建

一些题外话

⁶ 说通过 crictl info 找到 /var/lib/rancher/k3s/agent/etc/containerd/config.toml.tmpl 文件，然后修改这个文件中描述的 endpoint 地址

但是这个方案看起来特别奇怪。

⁷ 里面提到

启动时，K3s 会检查/etc/rancher/k3s/中是否存在registries.yaml文件，并指示 containerd 使用文件中定义的镜像仓库。如果你想使用一个私有的镜像仓库，那么你需要在每个使用镜像仓库的节点上以 root 身份创建这个文件。

但是通过 ³ 和 ⁴ 的方式安装之后，并没有出现 /etc/rancher/k3s/registries.yaml。

那么它是怎么知道 registry 的 mirror 是谁呢？

## 安装后的验证

kubectl get pods -n kube-system

TVM Dockerfile (CPU only)

junyi.h@comp.nus.edu.sg (Junyi Hou) — Thu, 15 Apr 2021 20:39:13 +0800

写了一个 Dockerfile，可以一键部署 TVM 的 CPU 版本

映射 container 端口 22 即可使用 ssh，用户名密码都是 tvm

在 GitHub 查看 Dockerfile

构建指令：

docker build -t tvm_cpu:0.7.0-x86_64 .

或者你也可以直接拉取我的镜像：

docker pull dockerjunyi/tvm_cpu:0.7.0-x86_64

使用方法：

# -p 容器内 22 端口映射到本地 2222
# -i 交互模式运行容器
# -t 开启伪输入终端（与 -i 连用）

# 运行一个容器，将容器内 22 端口映射到本地 2222，容器设置为交互模式，开启伪输入终端，容器 image 叫做 dockerjunyi/tvm_cpu:0.7.0-x86_64，同时执行容器内的 /bin/bash
docker run -p 2222:22 -it dockerjunyi/tvm_cpu:0.7.0-x86_64 /bin/bash

当然，运行起来容器之后，如果不想使用 docker 的交互模式，你也可以通过映射出的 ssh 端口来访问