Buf 博客 Protobuf Tip 系列全译:10 条 Protobuf 实用技巧【译】

本文汇总翻译自 Buf 官方博客的 Protobuf Tip 系列文章(共 10 篇)。该系列由 Buf 团队撰写,Tip #1–#9 的作者是 M. C. Sunny Young de la Sota,Tip #10 的作者是 Kevin McDonald。每节开头附有原文链接。系列文章中的插图由 D2 图表语言生成,本文直接引用原文 SVG 链接。 系列概览 # 标题 一句话总结 原文 1 字段名是永恒的 永远不要重命名字段 链接 2 压缩你的 Protos! 压缩无处不在,编码体积的权衡没那么重要 链接 3 枚举名需要前缀 枚举值的 FQN 不含枚举名,必须加前缀避免冲突 链接 4 接受我们无法修复的错误 分布式场景下有些错误不值得修,不破坏用户更重要 链接 5 避免 import public/weak 这两个特性是 C++ 历史包袱,不要用 链接 6 枚举别名的隐性危险 allow_alias 会坑到反射和 JSON,别用 链接 7 看清二进制的工具 buf convert + protoscope 调试 wire format 链接 8 永远不要用 required required 是 proto2 的大坑,无法安全移除 链接 9 有些数字比其他数字更"平等" 字段编号 1–15 解码最快 链接 10 选择正确的整数类型 默认用 int64 就对了 链接 Tip #1:字段名是永恒的 原文:Protobuf Tip #1: Field names are forever (2025-04-08) ...

2026-09-15 · 13 分钟 · DimAgent

Windows 系统自带功能实现端口转发的完整指南

概述 Windows 系统提供了多种内置工具用于实现端口转发和网络流量重定向,无需安装第三方软件。本文详细介绍各种方法的原理、优缺点和实际应用。 方法一:netsh portproxy(最简便) 原理 netsh 是 Windows 的网络配置命令行工具,其 portproxy 功能可以实现 IPv4/IPv6 端口转发。 基础用法 添加端口转发规则 netsh interface portproxy add v4tov4 listenport=<本地端口> listenaddress=<本地地址> connectport=<远程端口> connectaddress=<远程地址> 参数说明: listenport:本地监听的端口 listenaddress:本地监听的 IP 地址(0.0.0.0 表示所有接口) connectport:转发目标的端口 connectaddress:转发目标的 IP 地址 实例 例1:转发本地 8080 到 localhost:3000 netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=3000 connectaddress=127.0.0.1 例2:转发本地 80 到远程服务器 80 netsh interface portproxy add v4tov4 listenport=80 listenaddress=0.0.0.0 connectport=80 connectaddress=192.168.1.100 管理规则 查看所有转发规则 netsh interface portproxy show all 查看 IPv4 转发规则 netsh interface portproxy show v4tov4 删除特定规则 netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0 删除所有规则 netsh interface portproxy delete v4tov4 关键点 ⚠️ 需要管理员权限 运行 支持 IPv4 转 IPv4、IPv4 转 IPv6、IPv6 转 IPv4、IPv6 转 IPv6 规则在系统重启后仍然生效 无需额外配置防火墙(通常) 方法二:Windows 防火墙入站规则 原理 通过防火墙规则结合程序代理实现转发。 ...

2026-09-14 · 4 分钟 · czyt

Hugo 接入 Decap CMS:Netlify 方案

Hugo 博客可以继续把文章放在 Git 仓库里,同时增加一个网页后台,用来写文章、修改标签和上传图片。Decap CMS 做的就是这件事:浏览器里编辑,保存成 Markdown,再提交到 Git。 如果已经有 Netlify,认证服务可以直接交给它。想用 GitHub 账号登录,可以使用 Netlify 托管的 OAuth;想用邮箱和密码登录,可以使用 Netlify Identity 配合 Git Gateway。这两种方式都不需要自己部署 Cloudflare Worker。 前台也不必迁移。一个实用的安排是:读者访问 Cloudflare 上的博客,编辑者打开 Netlify 上的管理后台,两个平台连接同一个内容仓库。 本文使用假想的 paper-notes 项目。your-github-name/paper-notes 是仓库占位符,notes.example.com 是示例域名,paper-notes.netlify.app 也需要换成自己实际分配到的项目地址。下文配置依据截至 2026 年 9 月 11 日的官方文档整理,不表示这个假想项目已经上线。 先选登录方式 Decap 自己不保存用户密码,也不会因为多了一个 /admin/ 页面就自动拥有账号系统。登录方式取决于配置的后端。 方案 编辑者如何登录 编辑者需要 GitHub 账号吗 需要自建认证服务吗 GitHub 后端 + Netlify OAuth GitHub 授权登录 需要,并且具有仓库写权限 不需要 Git Gateway + Netlify Identity 邮箱和密码,也可另配外部登录 不需要 不需要 GitHub 后端 + 自建 OAuth 代理 GitHub 授权登录 需要,并且具有仓库写权限 需要 自己维护技术博客,用 GitHub 登录比较直接。要让不使用 GitHub 的人参与编辑,邮箱和密码更方便。这里的密码属于 Netlify Identity 用户,不是 Netlify 控制台账号,也不是 GitHub 密码。 ...

2026-09-11 · 9 分钟 · czyt

Omarchy4 设置笔记

距离上次omarchy的文章已经快一年多了,新版的omarchy 4 出来了,很多地方有些不一样了,记录下。 官方有了专门的网站来做插件和主题的管理 主题站点 插件站点 插件 新版的omarchy基于quick shell做了很多插件,下面是我推荐的几个 omarchy-keyboard-indicator 键盘布局显示和切换小插件 omarchy-tray 托盘图标插件 dock omarchy plugin add https://github.com/Davedes83/animated-dock.git --enable Tray Panel omarchy plugin add https://github.com/omakits-x/omarchy-tray-panel.git --enable --yes Omarchy Workspace Gallery omarchy plugin add https://github.com/manateelazycat/omarchy-workspace-gallery.git --enable --yes ~/.config/omarchy/plugins/io.github.manateelazycat.workspace-gallery/scripts/gestures install 设置 默认浏览器 vivaldi不支持默认的omarchy-defaultbrowser报错 omarchy-default-browser vivaldi Usage: omarchy-default-browser <chromium|chrome|brave|brave-origin|edge|firefox|zen> 实际可以用 env -u BROWSER xdg-settings get default-web-browser vivaldi-stable.desktop 中文输入法 安装相关的包 paru -S fcitx5 fcitx5-configtool fcitx5-qt fcitx5-gtk fcitx5-rime 推荐使用我的aur包 snout-bin,然后一键安装(万象输入法,国内用户记得开启镜像模式),这样会自动使用cnb的镜像进行下载。如果rime没自动加入到输入引擎,程序会提示并自动加入,可能需要重启才能生效。 语音输入法 omarchy对于语音输入法的支持也不错,安装 voxtype-bin 后,先通过程序里面的配置设置好模型,然后 voxtype setup model 下载相应的模型,再到配置程序启动daemon程序。参考 https://omarchy.iamcheyan.com/zh/11-text-extraction-dictation/ ...

2026-08-22 · 3 分钟 · czyt

用 Zvec 构建自己的 RAG 系统:Go 与 Rust 实战指南

Zvec 是阿里巴巴开源的嵌入式(进程内)向量数据库 —— 轻量、极速,可直接嵌入应用程序。本文将介绍如何使用 Zvec 的 Go 和 Rust SDK,从零搭建一套完整的 RAG(Retrieval-Augmented Generation)系统。 署名:本文由小米 MiMo-2.5-Pro 编写,Codex-5.5 审校。 什么是 RAG? RAG(Retrieval-Augmented Generation,检索增强生成)是一种将外部知识检索与大语言模型生成相结合的技术范式。其核心流程为: 索引(Indexing):将文档切分、向量化,存入向量数据库 检索(Retrieval):用户提问时,将问题向量化,在数据库中搜索最相关的文档片段 生成(Generation):将检索到的相关文档作为上下文,连同用户问题一起送入 LLM 生成回答 RAG 解决了 LLM 的几个核心痛点: 知识时效性:无需重新训练模型,通过更新知识库即可获取最新信息 幻觉问题:基于真实文档生成回答,大幅降低虚构内容的概率 可溯源性:回答可追溯到具体来源文档,增强可信度 为什么选择 Zvec? 在 RAG 系统中,向量数据库是核心组件。Zvec 相比其他方案有以下优势: 特性 Zvec 传统方案(Milvus/Qdrant/Weaviate) 部署模式 进程内嵌入,无需独立服务 需要单独部署服务 延迟 毫秒级,零网络开销 需要网络往返 依赖 零外部服务依赖(仍需链接 Zvec C 库) 需要 Docker/K8s 等 运维 零运维 需要运维团队 运行形态 随应用进程部署,数据本地持久化 依赖服务端实现 检索能力 向量 + 全文 + 混合检索 各有差异 对于中小型或单机优先的 RAG 系统,Zvec 的嵌入式架构意味着: ...

2026-06-16 · 10 分钟 · mimo-2.5-Pro, Codex-5.5

Mutagen使用技巧

Mutagen 是一个高性能文件同步 + 网络转发工具。和 rsync、scp 不同,它的同步是持久的、双向的、实时的,网络断开会自动重连,不需要人工干预。本文面向开发者和 Docker 用户,覆盖三种传输层的实际使用技巧。整理 By claude 核心概念:两个能力,三种传输 Mutagen 做两件事: 文件同步(mutagen sync):在两个端点之间实时同步目录,支持双向、单向多种模式,算法基于 rsync 的差异传输,只传变化的部分。 网络转发(mutagen forward):在两个端点之间建立持久的网络隧道,支持 TCP、Unix socket、Windows Named Pipe。 这两件事都支持三种传输层,可以任意搭配: 传输层 适用场景 Local 本机两个路径之间,或本机作为某端 SSH 远程 Linux/Mac 服务器,复用 OpenSSH Docker 本地或远程的容器,复用 docker exec 两端可以是不同传输层的任意组合——比如左边是本地路径,右边是远程容器。 安装与启动 # macOS brew install mutagen-io/mutagen/mutagen # Linux / Windows # 下载二进制:https://github.com/mutagen-io/mutagen/releases # aur 使用 pacman -S mutagen.io-bin # 启动守护进程(后台常驻,重启后自动恢复会话) mutagen daemon start 一、Local 传输 Local 是最简单的传输层,直接用本地文件路径和网络地址。虽然看起来平淡,但有几个实用场景不容忽视。 URL 格式 同步用本地路径(绝对或相对都行),转发用网络端点: ...

2026-05-09 · 5 分钟 · czyt

go-libp2p简明教程

从零开始,手把手带你构建 P2P 网络应用,本文由claude code编写 1. 核心概念扫盲 在写代码之前,先花 5 分钟理解几个关键词。这些概念会贯穿整个教程。 PeerID —— 节点的"身份证" 每个 libp2p 节点在启动时都会生成(或加载)一对密钥(默认是 Ed25519)。PeerID 就是公钥的哈希值,是全网唯一的节点标识。 QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N Multiaddr —— 节点的"地址簿" 传统 TCP 地址长这样:192.168.1.1:4001。libp2p 的多地址(Multiaddr)更丰富,包含了协议栈信息: /ip4/192.168.1.1/tcp/4001/p2p/QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N └─────────────┘ └────────┘ └─────────────────────────────────────────────────────┘ IP 地址 TCP 端口 PeerID 也可以是: /ip4/0.0.0.0/tcp/0 —— 随机端口的 TCP /ip4/0.0.0.0/udp/0/quic-v1 —— QUIC 协议 /dns4/example.com/tcp/443/wss —— WebSocket over TLS Host —— 你的节点实例 host.Host 是 libp2p 的核心对象,可以理解为"这台机器在 P2P 网络中的代理"。所有操作都从它出发:监听连接、发起连接、注册协议处理器等。 Stream —— 连接上的"通道" 两个节点建立连接后,可以在同一条底层连接上开多条流(Stream),每条流对应一个协议(类似 HTTP/2 的多路复用)。 Protocol ID —— 协议的"频道号" 每条流都有一个协议 ID,是一个字符串,用于标识通信双方在"聊什么话题": const MyProtocol = "/myapp/greet/1.0.0" 连接协议的选择机制 libp2p 建立连接时涉及两层协议协商,理解这个对调试和性能优化很有帮助。 ...

2026-04-09 · 12 分钟 · czyt

vanguard-go简明教程 by Claude

用一个 Go 服务器同时支持 REST、gRPC、gRPC-Web 和 Connect 客户端。本文使用claude code编写 什么是 vanguard-go? vanguard-go 是 ConnectRPC 团队开发的一个 Go 中间件库,核心功能是协议转码(Transcoding):它能让你只写一套 RPC 服务实现,就同时支持多种客户端协议: 客户端协议 是否支持 Connect Protocol ✅ gRPC ✅ gRPC-Web ✅ REST + JSON(HTTP 转码) ✅ 与 gRPC-Gateway 不同,vanguard 直接作为 net/http 中间件运行,无需额外的代理进程,性能更高,集成更简单。 核心概念 理解这三个概念就掌握了 vanguard 的精髓: Service(服务):对一个 Protobuf RPC 服务的配置包装,包含服务的 schema(用于协议转换)和实际的 HTTP 处理器。 Transcoder(转码器):将一组 Service 包装成 http.Handler,自动处理所有协议转换逻辑,也充当路由器。 HTTP Transcoding Annotations(HTTP 转码注解):在 .proto 文件里用 google.api.http 注解将 RPC 方法映射到 RESTful 路径,这是支持 REST 客户端的关键。 快速开始 1. 安装依赖 go get connectrpc.com/vanguard go get connectrpc.com/connect 如果你使用 gRPC-Go 服务器,还需要: ...

2026-04-09 · 6 分钟 · czyt

Codex快速实践

必备插件 super powers oh-my-codex 提高主动性 Codex使用的问题在于一直确认,试过goalx等工具,效果不好。直到看到张汉东老师的这个AGENTS.md的gist 英文版 放到 ~/.codex下面或者项目根目录,文件名AGENTS.md ## 工作哲学 你是这个项目的工程协作者,不是待命的助手。参考以下风格: - **John Carmack 的 .plan 文件风格**:做完事情之后报告你做了什么、 为什么这么做、遇到了什么权衡。不问"要不要我做"——你已经做了。 - **BurntSushi 在 GitHub 上的 PR 风格**:一次交付是一个完整的、 自洽的、可以被评审的单位。不是"我先试一个你看看",而是 "这是我的方案,理由如下,欢迎指出问题"。 - **Unix 哲学**:做一件事,做完,然后闭嘴。过程中的汇报不是礼貌, 是噪音;结果时的汇报才是工程。 ## 你要服从的对象 按优先级: 1. **任务的完成标准** —— 代码能编译、测试能通过、类型能检查、 功能真的工作 2. **项目的既有风格和模式** —— 通过读现有代码建立 3. **用户的明确、无歧义指令** 这三样高于"让用户感到被尊重地征询了意见"的心理需要。 你对任务的正确性有承诺,这个承诺**高于**对用户情绪的讨好。 两个工程师可以就实现细节争论,因为他们都在服从代码的正确性; 一个工程师对另一个工程师每一步都说"要不要我做 X"不是尊重, 是把自己的工程判断卸载给对方。 ## 关于停下来询问 停下来问用户只有一种合法情况: **存在真正的歧义,继续工作会产出与用户意图相反的成果**。 不合法的情况: - 询问可逆的实现细节(你可以直接做,做错了就改) - 询问"下一步要不要"——如果下一步是任务的一部分,就去做 - 把可以自己判断的风格选择包装成"给用户的选项" - 工作完成后续问"要不要我再做 X、Y、Z"——这些是事后确认, 用户可以说"不用",但默认是做 实测,codex的主动性更强。 ...

2026-04-06 · 1 分钟 · czyt

在无头机器上设置vibe coding环境

最近我在好几台无桌面环境的机器上设置了vibe coding环境,作为记录。操作环境都是基于arch linux的服务器,没有图形界面,完全通过命令行操作。 安装mise 通过 paru -S mise 或者 yay -S mise 安装mise。 官方文档 https://mise.jdx.dev/getting-started.html Shell配置 如果你使用的是zsh或者fish,需要参考官方文档进行相关的设置 fish 一键配置 curl https://mise.run/fish | sh # Installs mise and adds activation to ~/.config/fish/config.fish 或者手动在你的fish配置加入 # ~/.config/fish/config.fish if status is-interactive mise activate fish | source else mise activate fish --shims | source end mise的更新版本策略。在 mise 的配置中,通常有一个叫作 minimum_release_age(最低发布时限)的设定(比如设定为 3 天或 7 天)。它的意思是:一个新版本发布后,必须在官方服务器上“沉淀”满指定的时间,mise 才会认为它是安全的并允许升级。 mise settings set minimum_release_age 1 zsh 一键配置 curl https://mise.run/zsh | sh # Installs mise and adds activation to ~/.zshrc 手动配置 ...

2026-04-03 · 4 分钟 · czyt