系统底层 on 小盒子的技术分享

为什么手机信号格最多 5 格，而且每一格都是骗你的

Wed, 15 Apr 2026 13:31:00 +0000

上周末我跟朋友在一家小餐厅吃饭。

他刚换了华为的新旗舰，掏出来拍菜，拍得特别起劲。拍着拍着抬头跟我说，你看这信号，满格。上次我来这家店一格都没有，换个手机完全不一样。

我低头瞄了一眼自己的 iPhone。2 格。

我没接话。

换半年前，我大概率会跟着点头，说句确实新机天线牛。但最近因为一个偶然的原因，我知道了一件事。

手机信号格，根本就不是一个物理量。

它长得像物理量。塔往你手机上打信号，手机把信号强度换算成几条小竖线画在状态栏上，看上去跟温度计的水银柱没什么区别。

但它不是。

塔发给你手机的信号确实有一个客观单位，叫 dBm，4G 和 5G 里面用的具体指标叫 RSRP。这是整个通信行业的规矩，全世界同一个位置测出来都是同一个值，几十年没变过。可是从 RSRP 到状态栏上的「几格」这一步换算，是谁定的呢？

手机厂商自己。每家一套。关起门来拍脑袋。

苹果一套，华为一套，小米一套，OPPO 又是另一套。同一张桌子、同一张运营商卡，几台不同牌子的手机并排举起来，能给你凑出一整张阅读理解答案。大家都信以为真。

但这只是第一层。它还有第二层，所以连手机厂商都不是最后拍板的人。

2018 年 Google 发布 Android 9 的时候，悄悄在系统里加了一组 API，允许运营商通过一个叫 CarrierConfig 的机制，给手机远程下发信号条的阈值。直说就是，运营商可以告诉你的手机，RSRP 低于 -95 dBm 的时候显示 4 格，低于 -105 显示 3 格，低于 -115 只剩 1 格，具体数字由运营商自己填。两年后的 Android 11 把这套能力继续扩展到 5G NR 和 SINR 上，等于把信号条的每一个环节都交给运营商定义。

以前我一直以为，手上的 iPhone 或者某台安卓手机，是两家公司跟我之间的合同。手机公司告诉我塔有多强，我信它。结果从 2018 年开始，这个合同里悄悄多了第三方。

换一张运营商卡，同一台手机、同一个位置，信号格数量都可能跟着变。手机厂商不再是最后的裁判，运营商才是。

这一下以前很多事情对上了。比如我上次去东南亚出差，一落地接上当地网络，同一台 iPhone 信号格莫名其妙就变好了。之前我还以为是当地基站比国内强，回头想明白，大概率是本地运营商发了一套比国内宽松得多的阈值，好让你觉得，至少还能聊微信。

这些事其实都不新鲜。十六年前，苹果就当着全世界被同一个问题按在地上摩擦过一次。

那年是 2010 年，iPhone 4 发布三天之内，用户发现左手握住机身左下角那条金属接缝，满格信号会唰一下掉到一格甚至断线。这就是后来被写进科技史的 Antennagate 天线门。

苹果一开始的回应是乔布斯一封著名邮件，Just avoid holding it in that way，你别那么拿不就行了。但在幕后，苹果团队扎进去查问题的时候发现了一件比天线本身更让他们头皮发麻的事。iPhone 的信号条公式，写错了。

同年 7 月 2 日，乔布斯亲自署名的公开信出现在苹果官网。原话是，我们震惊地发现，我们用来计算信号条显示几格的公式完全是错的，在很多情况下比应该显示的多画两格。两周后 iOS 4.0.1 发布，把公式按 AT&T 推荐的值重写了一遍。去年 10 月有个开发者把这两个版本的固件反编译对比，挖出核心改动只有大约 20 字节。苹果最著名的公关危机之一，技术上的修复是 20 个字节。

按理说，一家巨头当众承认过「我们的公式完全错了」之后，行业应该吸取教训搞一个诚实点的显示。十六年过去了，结果完全不是。

苹果自己的状态栏样式倒是翻来覆去改过好几轮。iOS 7 那会儿把 5 条大竖线换成 5 个小圆点，2017 年 iOS 11 又改回 4 条竖线，官方理由是给 iPhone X 的刘海腾状态栏空间。有意思的是，苹果不光换样式，还顺手把满格的门槛也调了。AnandTech 当年拿 iPhone 7 Plus 实测过两代系统，iOS 10 要求 RSRP 强过 -60 dBm 才给你满格（5 个圆点），到了 iOS 11 这个门槛放宽到了 -65 dBm（满格是 4 条竖线）。5 分贝听起来不多，放在通信这行里已经是肉眼可见的一大截。同一台 iPhone 在一个 -62 dBm 的位置，iOS 10 只给你 4 格（5 格里的第 4 格），换成 iOS 11 就直接满格 4 条。多出来的那一格不是因为塔变强了，是因为系统升级那天，苹果悄悄把满格的门槛降了一档。

华为、小米、vivo、OPPO 也都一样。每家旗舰跟同一张 SIM 卡放在一起都能凑出三种不同答案，没有任何一家公开过自己的映射表。大家心照不宣地把「让你看着舒服」放在「让你看到真实值」前面。

说到「心照不宣」，顺便聊几件业内都知道、但运营商和手机厂商从来不会主动告诉你的事。

先说一个最常见的。信号满格跟你能不能打通电话、能不能发出去微信，根本是两回事。

信号条的公式不管哪家怎么定，算的都是你手机跟塔之间那根电波强不强，算出来的是一个单纯的接收功率。它只反映一件事，你离塔有多近、中间隔了多少墙。但它完全不反映另一件事，那个塔现在还有没有空位留给你。

你肯定遇到过这种场景。演唱会现场、跨年夜外滩、春运候车厅、世界杯的体育场，手机满格，微信发不出去，红包抢不到，电话打不通。真相是塔那头的信道资源已经被塞爆了。一个基站能同时服务的用户数有物理上限，超了之后新来的用户信号再强也上不去。信号条不管这个。它就跟一家酒店的大堂经理一样，永远微笑着告诉你我们这儿很豪华，从来不告诉你今晚没房。

再说一个你每天都在用但不知道原理的。你以为**「切一下飞行模式再关掉」**是个玄学小妙招，背后其实有实打实的技术原因。

手机在 idle 状态下挑基站有一个惰性原则，只要当前连着的那个塔没掉到阈值以下，手机就不会主动去换塔，哪怕旁边有一个更强的。这是 4G 和 5G 协议里写死的 cell reselection 机制，为的是省电和避免频繁切换抖动。所以你从好位置走到不好的位置，手机很可能还赖在原来那个早就不够用的老塔上，死死不放。这时候你打开飞行模式，手机断开所有射频连接，再打开它被迫重新扫一遍所有可用基站，挑一个最强的连上，信号就「突然变好了」。

最后一个。你状态栏上那个 5G 图标，很多时候跟 5G 没太大关系。

5G 有两种部署方式，SA 独立组网和 NSA 非独立组网。国内三大运营商早期铺的 5G 基本都是 NSA，简单说就是手机同时挂在 4G 和 5G 两个基站上，下行跑 5G 快一点，上行（你发微信、发朋友圈、发视频那些）还是走 4G。状态栏只告诉你显示了 5G，不告诉你上行其实还在 4G。

最离谱的例子发生在 2018 年底的美国。AT&T 直接把 4G LTE Advanced 的网络标成 5G E，E 是 Evolution 演进的意思，堂而皇之地在用户的 iPhone 和安卓机状态栏上显示「5G E」三个字。整个美国通信圈把这事儿嘲笑了整整两年。2019 年 1 月 7 日，T-Mobile 官方推特发了一个短视频，视频里有人往一台 iPhone 屏幕上贴了一张写着「9G」的便利贴，配文「没想到升级这么简单，我先去更新一下」。后来美国广告审查机构 NAD 正式建议 AT&T 停用 5G Evolution 这个说法，但那个 5G E 图标一直留在状态栏上没删。

说了这么多，你其实也能自己亲手看一眼塔发给你手机的东西到底有多强。

iPhone 上，打开拨号盘输入 *3001#12345#*，按绿色拨号键。手机会直接进入一个叫 Field Test Mode 的隐藏界面，里面有一个 RSRP 数字。负数，越靠近 0 越强。一般 -80 以上算不错，-100 到 -110 之间开始掉速度，-115 以下基本就是快断线的状态。iOS 18 之后这个界面还顺便加了 SINR，信号质量指标，数字越大越好。

Android 上拨号盘敲 *#*#4636#*#*，进入菜单里的「手机信息」或「SIM 卡状态」，就能看到原始的 dBm 读数。少数深度定制系统把这个入口堵上了，大部分机型还留着。小米用户也可以在设置 → 我的设备 → 全部参数里直接找到 SIM 卡状态。

下次你在一个信号满格但微信发不出去、电话打不通的地方，可以拨一下那个代码试试看。屏幕上跳出来的那个负数，才是今晚塔真正愿意送到你兜里的东西。至于状态栏上那几条小竖线，它从来不是一个测量结果。它是一家手机厂商、一家运营商、外加一个远在硅谷或者深圳的产品经理，三方坐在一起商量之后，决定「让你看着还行」的一个小动画。

回到开头那家小餐厅。我朋友那台华为满格，我那台 iPhone 2 格。它们其实都没错，也都没真对，只是两家不同公司的产品经理对「你应该感觉有多安心」给出的两种不同答案。那个塔呢，它从头到尾就在餐厅外面，不多不少地发它那一点 dBm。

会变的，只有兜里那块屏幕替它说出来的话。

为什么 .tar.gz 要两个后缀

Mon, 13 Apr 2026 23:00:00 +0000

前两天我在重新编译一版 nginx。

流程基本闭着眼睛都能走。wget 拉下来一个 nginx-1.27.4.tar.gz，tar -xzvf 解开，进目录，./configure，make，make install。

敲完 tar 那条命令的一瞬间，我突然愣了一下。

这个 .tar.gz，两个后缀。

我用了大概十几年，从来没认真想过为什么要两个。

顺着这事我又想起来，我这双手对 tar 的记忆完全是肌肉记忆，xzvf 这四个字母该按什么顺序，大脑是不参与的，手指自己会动。正因为是肌肉记忆，我还踩过一个经典坑，偶尔下载到没有顶层目录的 tar 包，照样一梭子解下去，几十个文件啪一下全炸到当前目录，瞬间把工作目录变成垃圾场。

那种时候我一边 ls | xargs rm 一边告诉自己下次一定先 mkdir。

但下次还是不会。

人对每天都在用的东西是最没好奇心的。

说回 .tar.gz。这两个后缀到底是什么关系，为什么非得拆成两个。

我带着这个疑问查了一圈，发现这事比我想象的有趣得多。它不是什么历史包袱，也不是约定俗成的命名习惯，它是两个时代两个工具掰着手指头拼出来的一个结果。

先说 tar。

tar 这个命令，最早出现在 1979 年 1 月的 Unix Version 7 里，AT&T 贝尔实验室做的。名字也没什么加密的缩写，就是 Tape ARchive。翻译过来，磁带归档。字面意思。

你可以想象一下 1979 年。那会儿大家备份数据靠的是磁带，就是老电影里那种两个圆盘转啊转的大盘子，数据一圈一圈顺序刻在带子上。你不能跳着读，也不能中间插一段，只能从头到尾一次性过。

tar 这个工具的出生使命，就是为了给磁带服务的。

所以它做的事情特别简单，就一个动作，把一堆小文件按顺序拼成一条长长的字节流，好让磁带机一口气写下去。

注意，我说的是「拼成一条流」。

tar 压根就不压缩。

你拿 tar 把一个 100MB 的目录打成一个包，出来的文件还是 100MB，一个字节都没省。它只是把这些东西排成一列而已，没做别的事情。

tar 文件内部的最小单位是 512 字节一块，这个数字也不是随便选的。它就是 Unix V7 文件系统磁盘扇区的大小。1979 年的一个选择，刻在所有 tar 文件的基因里，一直刻到今天。所以 tar 管的事情，就到「拼」为止。

那压缩呢？

tar 不管。

这事儿一直到 1992 年才有人接手。

那一年，两个叫 Jean-loup Gailly 和 Mark Adler 的人做了一个东西叫 gzip。Gailly 写压缩，Adler 写解压，1992 年 10 月 31 号，gzip 0.1 正式发布。

这里有个背景值得一提。在 gzip 之前，Unix 自带的压缩工具叫 compress，用的是 LZW 算法。但 LZW 被 Unisys 和 IBM 捏在手里，九十年代初开始到处收钱，开源圈被整得很紧张。gzip 就是被逼出来的替代品，用的是另一个叫 DEFLATE 的算法，完美绕开了专利地雷。

这段往事本身就够写一篇文章的，但今天我们只关心一个点。

gzip 做的事也特别简单，就一个动作，把一条字节流压缩成一条更短的字节流。

你注意到了吗？gzip 也很轴。它只认「一条流」。你不能拿 gzip 去压一个目录，它不认识目录这回事。给它一个文件，它就吐一个压缩后的文件，给它一条流，它就吐一条压缩后的流。别的事它一概不管。

tar 只打包不压缩，gzip 只压缩不打包。

两个工具，谁都不会干对方的活。

那怎么办？

中间用一根 Unix 管道粘起来。

1tar cf - mydir | gzip > mydir.tar.gz

这条命令左边 tar 把 mydir 打成一条流，用 - 表示「别写文件，直接吐到标准输出」。中间一个 |，把这条流接到 gzip 的嘴边。右边 gzip 啃完这条流，吐出一条压缩过的流，重定向到 mydir.tar.gz。

一个 | 符号，两个工具，一条流水线。

你看到的那个 .tar.gz，就是这条流水线走完之后自然掉下来的结果。它的后缀之所以是两个，是因为这个文件真的经历了两道工序。第一道叫 tar，第二道叫 gz。后缀诚实地告诉你它是谁。

这里顺便说一句 tar 后来的 -z 参数。

GNU tar 的作者们觉得每次写管道太烦，加了一个 z 参数，告诉 tar，你要压缩的时候帮我顺手调一下 gzip。这就是为什么我们今天敲 tar -xzvf 这个 z。但你要知道，是 tar 在「替你调 gzip」，不是 tar 自己会压缩。四十五年过去了，tar 本体始终没长出压缩这项能力。

这个决定非常 Unix，非常硬核。

有意思的是，几乎就在 tar 过着自己小日子的同一年代，大洋对岸的 DOS/Windows 世界走了完全不同的一条路。

1989 年，美国程序员 Phil Katz 在 DOS 上搞出 PKZIP，顺手发明了 .zip 格式。zip 跟 tar + gzip 的哲学几乎是正相反的，一个工具同时做两件事，既打包又压缩，一把梭到底。

四年之后的 1993 年，另一个年轻人进场了。俄罗斯程序员 Eugene Roshal 发布命令行 RAR，1995 年又推出图形界面版 WinRAR。RAR 是 Roshal Archive 的缩写，字面意思就是「Roshal 的归档」，一个用作者自己名字命名的格式，主打比 zip 更高的压缩率。

WinRAR 这个软件顺便还成了互联网历史上最著名的「永恒试用版」。它写着 40 天试用期，但过期后不会拦你，只会弹一个很客气的提示让你买 license，你关掉它接着用，下次再弹。这个 40 天续命了二十多年，全球无数人用了一辈子没付过钱，它也不生气。这事本身已经成了一个互联网梗。

这一路跟 Unix 那边的区别非常明显，一个软件管到底，打包压缩全包在一个 exe 里。后来 1999 年俄罗斯人 Igor Pavlov 又搞了开源的 7-Zip，自带一个 .7z 格式，压缩率再往上提一截。1996 年 Julian Seward 做的 bzip2、2009 年 Lasse Collin 做的 xz 也都先后加入了这个江湖，压缩格式的主要玩家基本就是这些人了。

但你注意到一个很好玩的分化没有。

bzip2 和 xz 这两个后来的家伙，在 Unix 世界里叫什么？.tar.bz2 和 .tar.xz。tar 先把文件拼成流，bzip2 或者 xz 接着压。换压缩工具可以，换哲学不行。Unix 那边认死一件事，打包和压缩必须是两件事，永远是两件事。

Windows 那边正相反，出了更强的算法，就把旧软件整个换掉，一个 exe 管到底。

这已经不只是格式之争了，是两个世界对「一个工具应该长成什么样」的根本分歧。

为什么 Unix 那边坚持要拆？

这就得搬出 Doug McIlroy 了。

1978 年，贝尔实验室的 McIlroy 在 Bell System Technical Journal 上写了一段后来被反复引用的话，核心就三句。

“

写程序要让它们只做一件事，并且把这件事做好。

写程序要让它们互相协作。

处理的东西最好是文本流，因为那是通用接口。

这就是后来被叫作 Unix 哲学的那一段。

但这段话最有意思的一点，不在文字本身。在于说这话的人是谁。

Doug McIlroy 不光是写这段话的人，他同时还是 Unix 管道 | 这个符号的发明者。

你品一下这个巧合。

他说「让程序互相协作」的时候，他心里想的不是什么抽象的合作，他想的就是管道。一个程序的输出，通过一根 |，无缝流进下一个程序的嘴里。小工具、单一职责、用管道粘起来，组合出任意复杂的流水线。

.tar.gz 就是这段话最直白的产物。

tar 是第一个只做一件事的小工具，gzip 是第二个只做一件事的小工具，中间那根 | 是 McIlroy 本人发明的管道。你每打一个 .tar.gz 文件，都是在重演一遍 1978 年那段话。

这就是为什么我说它是活化石。

化石这个词听起来像是死掉的东西，但 .tar.gz 不是。你今天去 GitHub 上随便点一个 C 项目的 release，下载下来的几乎永远是 .tar.gz，不是 .zip。Linux 内核、nginx、curl、redis，全都是。它不是因为惯性才活着，它是因为那套哲学在今天依然被认为是对的才活着。

所以回到开头那个问题。

为什么 .tar.gz 要两个后缀？

因为它不是一个文件，是两个工具排成的一条流水线，每个后缀对应一个工位。你看到的是这条流水线吐出来的结果。

下次你再敲 tar -xzvf some-thing.tar.gz 的时候，可以稍微多看两眼那个 z。

那个 z 不是 tar 在解压。

那是 tar 在回头喊一声 gzip，过来搭把手。

两个工具，一根管道，四十五年。

OpenClaw 爆火背后：它不是聊天机器人，而是一套真正会做事的 AI 系统

Wed, 11 Mar 2026 10:14:30 +0000

如果你最近在 GitHub 上关注过 AI Agent 领域，大概率已经看到过 OpenClaw。到 2026 年 3 月 10 日，它的 GitHub 仓库已经来到约 297k stars，超过了 React 的约 244k 和 Linux 的约 222k。更重要的不是数字本身，而是它火起来的方式：它不是靠一个漂亮网页，也不是靠一个“会聊天的套壳”，而是靠一整套把大模型接入真实消息渠道、真实设备、真实浏览器、真实文件系统的系统架构，硬生生把“AI 助手”做成了一个长期在线的工程系统。

但如果你只把 OpenClaw 理解成“接了很多 IM 的机器人”，你会完全错过它最有价值的部分。OpenClaw 官方 README 写得很直白：“The Gateway is just the control plane — the product is the assistant.” 这句话几乎就是读懂整个项目的钥匙。它的重点从来不是“有多少入口”，而是：有没有一个统一控制面，把消息、状态、路由、模型、工具、节点、权限和安全边界收在一起。 README、架构文档和 Vision 文档都在强调同一件事：OpenClaw 想做的是“真正会做事的 AI”，运行在你的设备、你的渠道、你的规则之内。

这篇文章，我想尽量回答七个问题：

1.它到底是什么？

2.它为什么会采用现在这套架构？

3.Gateway 到底在系统里扮演什么角色？

4.Agent 是怎么运行起来的？

5.Memory、Workspace、Session 为什么是它的关键设计？

6.多 Agent、节点、工具体系是怎么拼到一起的？

7.以及最后，为什么它值得被看作下一代 AI 助手的典型系统样本。

在回答这些问题之前，我不得不说，现在龙虾有些过热了，对于想 “卖铲子” 的公司当然觉得这是好事，于是他们推波助澜，但对于专业人士不能人云亦云。openClaw 有它优秀的一面，也有被炒作夸大的一面，应该客观地看。

一、OpenClaw 的本质，不是聊天机器人，而是“个人 AI 助手控制面”

一句话定义 OpenClaw，我会这样说：

OpenClaw = 一个以 Gateway 为中心的个人 AI 助手控制平面，下面挂着嵌入式 agent runtime、会话系统、工具系统、消息渠道、节点设备和安全边界。

这个定义不是我自己拔高出来的，而是官方文档本身就在往这个方向写。

●README 说它是“你运行在自己设备上的 personal AI assistant”；

●架构文档说它是一个 single long-lived Gateway，拥有所有 messaging surfaces；

●Vision 文档则把它描述为“the AI that actually does things”，运行在你的设备、你的渠道、你的规则里。

把这些信息放在一起看，你会发现 OpenClaw 的设计起点根本不是一个“聊天 UI”，而是一个长期在线、可被多入口触发、可调用工具、可连接设备、可持续维护状态的 AI 系统。

这也是为什么我认为 OpenClaw 更接近“控制面”而不是“应用层”。在很多 AI 产品里，用户打开网页，输入问题，后端调一下模型，返回一段文本，交互就结束了。OpenClaw 则完全不是这种形态。它默认有一个长期运行的 Gateway 进程，消息渠道接到这个 Gateway，上层的 CLI、Control UI、WebChat 接这个 Gateway，macOS/iOS/Android/headless 节点也接这个 Gateway，甚至定时任务、exec approvals、pairing 和 health 事件都围绕 Gateway 展开。也就是说，Gateway 不是一个消息转发器，而是系统中枢。

二、Gateway 为什么是 OpenClaw 最关键的设计

OpenClaw 官方架构文档里最重要的一句话，是它把 Gateway 明确成 single control plane。一个长期运行的 Gateway 拥有所有 messaging surfaces；control-plane clients 通过 WebSocket 连进来；nodes 也通过 WebSocket 连进来，但会声明自己是 role: node；Canvas host 也由 Gateway 的 HTTP server 提供，而且默认和 Gateway 共用 127.0.0.1:18789 这个端口。

这意味着什么？意味着 OpenClaw 的系统设计不是“每个端各做一套逻辑”，而是“先做一个统一控制面，再让所有端接入它”。这在工程上有三个非常大的好处。

第一，状态是统一的。

会话在哪里维护？在 Gateway。

路由在哪里决策？在 Gateway。

设备配对、认证 token、事件广播、健康状态、cron、工具审批在哪里收敛？还是在 Gateway。

这让系统不会因为前端入口变多而出现多套状态、多个事实来源。

第二，协议是统一的。

Gateway protocol 文档明确写了：OpenClaw 不是“随便传一段 JSON”，而是有明确握手流程和版本约束的 WebSocket 协议。服务端先发 connect.challenge，客户端再带着 device identity、role、scopes、caps、auth、签名等参数发起 connect，通过后才返回 hello-ok。协议版本有 minProtocol/maxProtocol 协商，协议 schema 由 TypeBox 定义，再生成 JSON Schema 以及 Swift model。对一个跨 CLI、网页、桌面、移动端、节点设备的系统来说，这种 typed protocol 的价值非常高。

第三，能力是统一暴露的。

比如 Control UI 不是一个独立后端，而是 Gateway 在同一端口上提供的浏览器管理界面；WebChat 直接连 Gateway WebSocket；nodes 也不是第二套服务，而是带 role:node 的外围设备。也就是说，OpenClaw 并不是“一个 App + 一堆外挂”，而是“一个控制面 + 多个表面”。

很多人第一次看 OpenClaw，会把注意力放在“它居然支持这么多渠道”。但真正懂架构的人，会先看 Gateway。因为能不能把多个入口、多种设备、多条事件流、多种工具执行方式，全都压到一个长期运行的控制面里，决定了它到底是“一个功能”还是“一个系统”。OpenClaw 的做法很明确：先有控制面，再有助手。

三、它最强的抽象，不是对话框，而是 Agent、Session 和 Route

很多 AI 产品最基础的抽象单位是“聊天窗口”。OpenClaw 不是。

OpenClaw 的真正基础模型，是：

●谁来回复（Agent）

●回复落在哪段连续上下文里（Session）

●一条消息应该被路由到哪个 agent 和哪个 session（Route）

Agent：一颗完整隔离的大脑

Multi-Agent 文档里写得很清楚：一个 agent 是一个 fully scoped brain，拥有

●自己的 workspace

●自己的 agentDir

●自己的 auth profiles

●自己的 session store

它的文件、人格、配置、认证信息和会话历史都是围绕这个 agent 单独组织的。默认路径也很清晰：

●workspace 在 ~/.openclaw/workspace 或 workspace-<agentId>

●session 存在 ~/.openclaw/agents/<agentId>/sessions

●auth profile 在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

这件事非常重要。因为这说明 OpenClaw 的多 Agent，不是“在一个上下文里换不同 system prompt 假装多人格”，而是真的把状态、身份、凭证和工作目录做成了隔离单元。但要注意，这种独立是为了让系统跑得更有条理，属于“防君子不防小人”的内部隔离。官方的意思很明确：同一个网关（Gateway）里的 Agent 默认都是“自己人”，不能把互不信任、甚至带有敌意的任务强行塞进同一个网关里，它并没有提供那种级别的安全防御。

Session：上下文连续性的主键

Session 文档里有一句特别关键的话：

OpenClaw treats one direct-chat session per agent as primary.

这句话可以理解成：对每一个 agent，OpenClaw 都认为它有一个“主私聊会话”

OpenClaw 默认会将一个 Agent 接收到的所有私聊（Direct Message, DM）都汇聚到一个主会话里（即 agent:<agentId>:<mainKey>）。对于群聊、频道或特定的话题（Thread），则会自动拆分独立处理。

对于 direct chat， agent 有一个规范意义上的主会话；默认所有 DM 都往这里归并，以保证连续性。

假设你有一个 agent 叫 main。默认情况下：

●你在 Web UI 私聊它一次

●之后又在 CLI 私聊它

●再后来在手机端私聊它

如果这些都被识别为 direct chat，而且你没有改 session.dmScope，那么这些私聊会折叠进同一个主 session,这样做的好处是：agent 会把这些私聊视为同一条连续对话，而不是三个彼此割裂的会话。

默认的主会话机制在单用户场景下很完美，但在多用户场景下就是一个巨大的安全漏洞。

如果 Alice 和 Bob 都去私聊同一个 Agent，在默认配置下，他们实际上是在向同一个“上下文沙箱”里写入数据。这就好比两个人共用一个日记本：

●Alice 刚和 Agent 聊完财务密码。

●Bob 接着去问 Agent“我们刚才聊了什么？”

●Agent 就会直接把 Alice 的密码复述给 Bob，造成严重的信息泄露。

为了应对多用户场景，OpenClaw 提供了 session.dmScope 配置，允许你在架构层面把私聊的上下文切分成更安全的细粒度：

●按发信人隔离（per-peer）。

●按频道+发信人隔离。(per-channel-peer)

●按账号+频道+发信人隔离(per-account-channel-peer)。

⚠️ 如果你在开发面向多用户的 AI Agent，绝对不能盲目使用默认的私聊配置。必须根据业务需求，通过调整 dmScope 将用户的对话状态彻底隔离开，防止你的 Agent 变成一个没有隐私边界的“大喇叭”。

Route：决定消息进入哪颗大脑

Channel Routing 文档把消息路由规则写得非常明确，一条消息发过来，绝对不是“哪个 Agent 闲着就扔给谁”，而是像网关（Gateway）匹配规则一样，必须严格按照优先级一层层往下筛，直到找到唯一确定的接收者。

我们可以用**“公司收发室分拣快递”**来打个比方，看一下这 5 层降级（Fallback）匹配规则：

1.精准单聊 (Exact peer match)：快递单上写着“直接交到张三本人手里”。

○明确的点对点直接交互，优先级最高。

2.跟帖/线程继承 (Parent peer match)：快递单没写名字，但备注了“这是昨天那个加急件的补充材料”。收发室一查昨天是李四负责的，直接给李四。

○识别 Thread 或上下文，让同一个 Agent 连贯处理同一个话题。

3.平台级群组与角色 (Discord guild+roles / Slack team)：快递写着“给财务部经理”或“给核心开发组”。

○根据外部平台（如 Discord/Slack）的特定权限组或大团队来分配对应的 Agent。

4.账号与频道 (Account / Channel)：快递写着“送到 3 楼会议室”或“交给官方客服号”。

○匹配特定的聊天频道或绑定的公共账号。

5.默认兜底 (Default agent)：啥也没写清楚的无主件，统统扔给“前台总机”处理。

○如果上面所有条件都未命中，最后由默认的 Agent 统一接管。

这意味着 OpenClaw 的“消息归属”不是模糊的。一条消息不是“谁在线谁回”，而是经过一套确定性规则，先判定该由哪个 agent 接管，再决定落到哪个 session 里。

所以 OpenClaw 能天然处理这些现实世界场景：

●同一个 Gateway 托管多个 agent；

●一个 Telegram 群给 work agent；

●一个 WhatsApp 家庭群给 family agent；

●一个 Slack team 给 support agent；

四、Agent 不是外挂调用，而是嵌入式运行时

很多人对 OpenClaw 最大的误解，是把它当成了一个简单的“任务调度员”——以为它只是在收到消息时，拉起一个外部的子进程（Subprocess）去跑一下，或者通过接口（RPC）远程调一下就完事了。

但架构文档明确指出：OpenClaw 是将 Agent 运行时“原生内嵌”到自己的网关里的。它不是把 Agent 当作一个不可控的外部黑盒，而是直接在内部实例化 Agent 的核心会话（AgentSession）。

Pi Integration Architecture 文档写得非常明确：OpenClaw 不是把 pi 作为 subprocess 或 RPC mode 的外部黑盒去调用，而是直接导入并实例化 pi 的 AgentSession，通过 createAgentSession() 把 agent runtime 嵌入到自己的消息网关架构里。

这种“深度内嵌”的架构设计，直接赋予了系统 6 大核心优势：

1.全局生命周期掌控：从对话的创建、挂起、恢复到销毁，网关层拥有绝对的控制权。

2.动态能力扩展：可以在运行时，随时把自定义的外部工具“塞”给 Agent 使用。

3.“看人下菜碟”的人设：能够根据消息来源（不同的平台渠道或上下文），动态切换 Agent 的系统提示词。

4.强悍的记忆管理：不仅能持久化保存对话，还支持高级的“记忆压缩（Compaction）”防止上下文爆满，甚至支持像 Git 一样对对话“开分支（Branching）”。

5.智能凭证轮询：在多个账号或 API Key 之间自动无缝切换，轻松应对并发和限流问题。

6.模型厂商解绑：底层的大模型想换就换，完全不受单一服务商（如 OpenAI、Anthropic）的绑架。

简单来说，OpenClaw 走的是“直接收编”的路线，它把 Agent 的核心大脑直接“拔”过来，原生种植在了自己的神经中枢里。这就好比你不再是打电话咨询外部专家，而是直接把这位专家招进了自家的核心指挥部。正因为“人”彻底成了内部员工，你才能拥有上帝视角般的掌控力：你可以全面接管他的作息安排（会话生命周期），随时往他手里塞各种定制兵器（动态注入工具），根据不同场合要求他扮演不同的角色（按渠道切换提示词），像操作代码仓库一样去整理甚至分叉他的记忆（支持压缩与分支的持久化），甚至连他背后的“脑力供应商”（随时无缝切换各家大模型）和权限账号，都能在底层悄无声息地替他自动轮换。说白了，OpenClaw 不是在和 Agent “跨部门合作”，而是直接把 Agent 融为了自己身体的一部分。换句话说，OpenClaw 不是“在用一个 agent”，而是“在拥有一个 agent runtime，并把它纳入自己的控制面”。这也是它跟很多“外接 Agent SDK 的应用层产品”最大的差别之一。别人只是调用，OpenClaw 是接管。

五、Agent Loop：一条消息的"真实旅程"

前面我们讲了 Gateway 如何把消息路由到正确的 Agent。现在让我们跟随一条消息，看看它进入 OpenClaw 后，到底经历了什么。

不是"一次请求"，而是一个完整生命周期

如果你习惯了网页聊天框的"发消息→等回复"模式，OpenClaw 的处理方式会让你有点意外。

传统模式：

⚡ 代码片段用户发消息 → 后端调用模型 → 返回文本 → 结束

OpenClaw 模式：

⚡ 代码片段用户发消息 → 分配 runId → 解析 session → 装配上下文 → 运行 agent → 流式返回事件 → 持久化 session → 结束

这一条链路，实际上就是你给 OpenClaw 发一句话之后，系统内部真实发生的事情。它不是“一次 HTTP 请求”，而是一个完整的运行生命周期。

OpenClaw 把你的消息视为一个进程而非请求。它会给这个进程分配ID、监控生命周期、管理并发、持久化状态。

并发控制：为什么同一聊天窗口的消息要"排队"？

想象一下这个场景：你在 Telegram 连续发了三条消息：

●“帮我查一下明天天气”

●“顺便看看日程”

●“把第一封邮件标为已读”

如果这三条消息并发执行，会发生什么？

●Agent 可能先处理了邮件，再处理天气

●Session 历史会乱序写入

●工具调用可能互相冲突

OpenClaw 的解决方案很简单：每个 session 串行化执行。这不是性能问题，而是状态一致性问题。长期在线的助手，必须保证"记忆"不会被乱序操作搞乱。是防止工具竞争和状态污染的工程必要选择。

流式事件：你看到的不是"打字动画"，而是真实的工作过程

OpenClaw 的流式输出，不是简单的"逐字显示"，而是三种事件流：

为什么要这样设计？因为这让用户能真正"看到 AI 在工作"。不是动画，不是假进度条，而是系统内部真实发生的事件被推送到前端。它的体验更像一个"正在办公的助手"而非"死寂的输入框"

六、真正让它“像一个人”的，不是模型，而是 Workspace、System Prompt 和 Memory

很多人体验 OpenClaw 后会有一种明显感觉：它比普通网页聊天更像一个“持续存在的助手”。这种感觉，核心不是来自模型，而是来自它对工作区、提示词和记忆的系统化设计

Workspace：AI 的家，而不是一个临时目录

简单说，Workspace 就是 AI 的"家"：

●它有固定的位置（~/.openclaw/workspace/）

●它有固定的文件结构

●它是 AI 长期工作的地方，不是临时落脚点

OpenClaw 在 Workspace 里约定了一整套"说明书文件"：

这个设计特别妙。因为它把很多系统会偷偷塞进 prompt 模板或数据库里的东西，变成了用户可见、可读、可改、可备份的文件系统资产。你不是在“配一个人设”，而是在维护一个 AI 的长期工作环境。

这里有一个非常重要的提醒：workspace 是默认工作目录，但不是硬沙箱（hard sandbox）；相对路径默认在 workspace 内解析，但绝对路径仍可能访问宿主机其它位置，除非你开启 sandbox。

System Prompt：每次运行都在"编译上下文"

OpenClaw 不是把用户的问题直接扔给模型，而是每次都重新构建一份完整的上下文：

1⚡ 代码片段System Prompt 结构：
2├── Tooling（可用工具列表）
3├── Safety（安全规则）
4├── Skills（技能列表）
5├── Workspace Context（工作区文件）
6├── Documentation（相关文档）
7├── Current Date & Time（当前时间）
8└── Runtime（运行环境信息）

Context 文档还补充了细节：默认会把 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md 等文件作为 Project Context 注入系统提示；技能本身只会注入“技能列表和描述”，真正的 SKILL.md 需要模型按需读取。

类比：

●传统聊天：像"临时起意打电话"

●OpenClaw：像"开会前先发会议议程和背景资料"

Memory：真正写到磁盘，才算记住

Memory 文档里我最喜欢的一句话是：

The files are the source of truth; the model only “remembers” what gets written to disk.

OpenClaw 默认的记忆结构非常简单，但非常工程化:

1⚡ 代码片段workspace/
2 ├── memory/
3 │ ├── 2026-03-10.md ← 今天的日志
4 │ ├── 2026-03-09.md ← 昨天的日志
5 │ └── ...
6 └── MEMORY.md ← 长期、精炼的永久记忆

两种记忆的区别：

检索机制：不是"只有文件"，也不是"只有向量"

OpenClaw 使用混合检索,它明确暴露了两个 agent-facing tools：

●memory_search 负责检索

●memory_get 负责精确读取某个 Markdown 文件或行段

1⚡ 代码片段用户问"我上次出差去哪了？"
2 ↓
3 BM25 关键词检索 ← 精确匹配"出差"
4 +
5 向量语义检索 ← 理解"去哪了"是问目的地
6 ↓
7 MMR 重排序 ← 去重、多样化
8 ↓
9 返回最相关的几条记忆片段

记忆刷新：在"遗忘"前先"存档"

OpenClaw 有一个很巧妙的设计：pre-compaction memory flush

当 session 接近上下文上限（比如对话太长，快塞不进模型窗口了），OpenClaw 会：

●触发一次"静默回合"（用户看不到）

●提醒模型：“把值得记住的信息写入记忆文件”

●然后再压缩上下文

七、工具体系：分层设计，不是堆砌功能

如果说 Gateway 是控制面，Session 是状态骨架，那么 Tools / Plugins / Skills 就是 OpenClaw 的执行肌肉。

OpenClaw 的工具体系有三个层次，很多人会混淆。让我们分清楚：

Tools：第一等公民

OpenClaw 暴露的是 first-class agent tools，不是外挂脚本。包括 browser、canvas、nodes、cron、gateway、session 相关工具、agents_list、image、pdf、message、exec 等。

OpenClaw 没有把“能力调用”做成 prompt 技巧，而是做成了运行时契约。Tool list 和 tool schema 会进入模型上下文；tool allow/deny、tool profiles、per-agent 工具策略、provider-specific 工具策略和 sandbox 工具策略共同决定模型实际能拿到哪些工具

Plugins：扩展系统本身

插件是运行在 Gateway 内部的代码模块，可以：

●注册新的 RPC 方法

●添加新的 HTTP 路由

●注册新的工具

●启动后台服务

类比：

●Skills：像"使用说明书"

●Tools：像"内置功能"

●Plugins：像"给系统装新器官"

Skills：教 AI 如何做事

每个 Skill 就是一个目录，核心是 SKILL.md——一份详细的操作指南。Skill 的三个来源（优先级从高到低）：

●<workspace>/skills/：当前工作区专属

●~/.openclaw/skills/：用户私有技能

●Bundled skills：系统内置技能

与Plugins的本质区别:Plugins是给手机增加新硬件（如外接摄像头）；Skills是相机APP里的"夜景模式"说明书。

八、Node：让 AI “有手有眼”

OpenClaw 严格区分了两个概念：

为什么这样设计？

如果把它们混在一起：

●Telegram Bot 只能干 Telegram 允许的事

●WhatsApp Bot 只能干 WhatsApp 允许的事

每个渠道都要重新实现一遍"控制电脑"的能力

OpenClaw 的设计：

●所有消息渠道都汇聚到 Gateway

●所有设备能力也汇聚到 Gateway

Gateway 负责调度：“这个 Telegram 消息需要控制 iPhone，我来协调”

Node 是什么？

node 是 companion device，可以是 macOS、iOS、Android 或 headless 设备；它通过和 operator 一样的 Gateway WebSocket 接入，但使用 role: “node”，向 Gateway 暴露一组命令面，比如 canvas.、camera.、device.、notifications.、system.*，再由 node.invoke 触发。官方还特别强调：nodes are peripherals, not gateways。消息还是落在 Gateway，不是落在 node

Node 是一台"伴侣设备"，它：

●通过 WebSocket 连接到 Gateway

●向 Gateway 暴露一组能力（camera、notifications、system…）

●等待 Gateway 的指令

类比：

●Gateway：大脑

●消息渠道：耳朵和嘴

●Node：手和脚

没有 Node 的话：

●Telegram Bot 无法直接控制你的 iPhone

●需要你自己手动截图,再发给 Bot

●AI 无法真正"替你做事"

有了 Node：

●AI 可以跨设备协同工作

●你在 Telegram 发指令,它在你的 Mac 上执行

●真正的"个人助手"体验

九、安全边界：诚实比承诺更重要

OpenClaw 的安全模型假设的是 one trusted operator boundary per gateway

OpenClaw 的安全文档非常诚实，这句话翻译成人话是：

这意味着：如果你把Gateway密码给朋友，让他也连进来，你们的对话历史、文件访问、记忆内容默认不隔离。这不是漏洞，是设计选择——为了简化架构，OpenClaw牺牲了多租户隔离，换取单用户场景下的极致能力。

安全层次

 1⚡ 代码片段外层：公网/外部消息源
 2 ↓
 3第一道门：Gateway 入口保护
 4 - token/password 认证
 5 - challenge 签名验证
 6 - device identity 校验
 7 - pairing 审批
 8 ↓
 9第二道门：权限控制
10 - operator / node 角色
11 - scopes 权限范围
12 ↓
13第三道门：执行保护
14 - tool policy（工具策略）
15 - exec approvals（执行审批）
16 - sandbox（沙箱隔离）
17 - allowlist（白名单）
18 ↓
19内层：高风险边界
20 - plugins = trusted code
21 - 插件和 Gateway 同等权限

Sandbox：可以隔离，也可以放行

OpenClaw 的沙箱设计非常灵活：

配置维度：

●mode：off / non-main / all（是否启用沙箱）

●scope：session / agent / shared（沙箱范围）

●workspaceAccess：none / ro / rw（工作区访问权限）

实际用法举例：

浏览器隔离：不是接管你的 Chrome

OpenClaw不会接管你的日常Chrome（那里面可能有银行登录态），而是拉起独立的Chrome Profile：

●独立的Cookie、缓存、扩展

●Agent专用，与你的个人浏览数据隔离

●支持截图、点击、PDF生成，但无法访问你个人的浏览器历史

这是"能力"与"安全"的折中：AI需要浏览器自动化，但不能拥有你的全部数字生活。

十、为什么这是"个人AI操作系统"的雏形？

OpenClaw 之所以值得研究，不是因为它 GitHub stars 多，而是因为它回答了一个未来会越来越重要的问题：

如果 AI 不再是网页对话框，而是一个长期在线、能操作设备、能记住一切的助手，它的系统架构应该长什么样？

OpenClaw 的答案是：

这套答案不一定是终局，也还远没到“完美”。Vision 文档自己都说，项目还很早，当前重点依然是 security、safe defaults、bug fixes、stability 和 setup reliability。也就是说，它依然在快速迭代，仍然带着实验性。

但它已经足够有代表性。因为它第一次比较完整地把“个人 AI 助手”这件事，从概念拉成了系统工程：

●消息不再只是消息，而是事件入口；

●模型不再只是回答器，而是运行时里的推理核心；

●工具不再只是 function calling 演示，而是被策略、审批和沙箱约束的系统调用；

●记忆不再只是“模型好像记得”，而是落到磁盘、可检索、可审计、可 Git 备份的工作区资产

它具备了"操作系统"的味道

不是说它替代 Windows 或 macOS，而是说它有那种系统级的感觉：

1⚡ 代码片段传统应用：打开 → 用 → 关闭
2操作系统：开机 → 长期运行 → 管理所有应用 → 关机
3
4传统 AI：聊天 → 结束
5OpenClaw：启动 Gateway → 长期在线 → 管理所有 Agent → 关闭

最后，再强调一次：OpenClaw 的本质，不是一个接了很多渠道的聊天 Bot，而是一套以 Gateway 为控制面、以 Agent/Session/Memory 为状态骨架、以工具与节点为执行面，把大模型真正接入现实世界的个人 AI 助手系统。

如何快速判断论文是否值得研究

Mon, 13 Oct 2025 03:47:17 +0000

看被引用次数

比较简单粗暴，但好用，被引用的多了，自然值得关注。

工具：Google Scholar（免费、覆盖广）

但对于刚发的预印本还来不及积累引用的情况就不太适用了。

看影响力质量而不是只看数量

通过 Semantic Scholar 的 Highly Influential Citations 看 “被引里有多少是高度影响（不是随口一提）”

是否上过权威榜单/评测台

去 Papers with Code 看这篇（或同系工作）是否进入 SOTA 表格；很多任务有统一排行榜，能直观看到是否真压过强基线。目前 Papers with Code 已并入 Hugging Face:https://huggingface.co/papers/trending

“注意力热度” 作为早期信号

OpenAlex(https://openalex.org/) 能查近期新增引用与元数据，给你 “增长率” 而不是静态总量

2 / 3 规则

满足下列任意两项就放进 Top 10：

1.同主题近 6 个月被引增速靠前

2.SOTA 性能与基准：如果该论文的实验结果在如 MTEB、BEIR 等基准中取得了 SOTA 或接近 SOTA 的成绩，说明该论文提出的方案在当前技术生态中具有较强的竞争力。

3.GitHub + HF 同时在近 30 天明显上升（而不是一日游）

最后一条

玄学：看个人经验 😄

其他工具

Litmaps

Litmaps 是一个专为学术研究人员设计的文献管理工具，尤其适用于文献的可视化管理和关系图谱构建。它通过图形化的方式帮助用户了解不同学术论文之间的联系和发展脉络，进而促进研究人员在特定领域内进行深入的文献综述与研究。

快速安装 ClickHouse

Thu, 17 Jul 2025 09:33:05 +0000

概述

我们使用 docker compose 来安装 ClickHouse

但我们不是裸装 ClickHouse，实际上我们安装的是 ClickStack。有点儿像 elastic-stack 与 elastic search 的关系，但并不完全一样。

ClickStack 是基于 ClickHouse 构建的完整观察性平台，集成了日志、指标、追踪和会话回放功能，提供统一的用户界面和查询能力。因此，ClickStack 是在 ClickHouse 的基础上，结合 HyperDX 提供的前端界面和 OpenTelemetry Collector 实现的完整解决方案。它不仅仅是一个数据库，而是一个集成的观察性平台。

安装步骤参考官方文档：https://clickhouse.com/docs/zh/use-cases/observability/clickstack/getting-started?loc=use-case-observability

安装

克隆 HyperDX 仓库

1git clone https://github.com/hyperdxio/hyperdx.git
2
3cd hyperdx
4
5# switch to the v2 branch
6git checkout v2

根据自身情况修改配置文件 .env

我将 HDX_IMAGE_REPO=docker.hyperdx.io 修改为 HDX_IMAGE_REPO=docker.io 不然镜像拉不下来

 1# Used by docker-compose.yml
 2HDX_IMAGE_REPO=docker.hyperdx.io
 3IMAGE_NAME=ghcr.io/hyperdxio/hyperdx
 4IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx
 5LOCAL_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-local
 6LOCAL_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-local
 7ALL_IN_ONE_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-all-in-one
 8ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-all-in-one
 9OTEL_COLLECTOR_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-otel-collector
10OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-otel-collector
11CODE_VERSION=2.0.5
12IMAGE_VERSION_SUB_TAG=.0.5
13IMAGE_VERSION=2
14IMAGE_NIGHTLY_TAG=2-nightly
15IMAGE_LATEST_TAG=latest
16
17# Set up domain URLs
18HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
19HYPERDX_APP_PORT=8080
20HYPERDX_APP_URL=http://localhost
21HYPERDX_LOG_LEVEL=debug
22HYPERDX_OPAMP_PORT=4320
23
24# Otel/Clickhouse config
25HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

docker compose 启动

1docker-compose up -d

Docker-compose 文件如下：

 1name: hdx-oss
 2services:
 3 # ONLY USED FOR DEMO SSL SETUP
 4 # nginx:
 5 # image: nginx:1.27.3
 6 # volumes:
 7 # - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
 8 # - ./docker/nginx/ssl:/etc/nginx/ssl
 9 # - .volumes/nginx_logs:/var/log/nginx
10 # ports:
11 # - 80:80
12 # - 443:443
13 # networks:
14 # - internal
15 # depends_on:
16 # - app
17 db:
18 image: mongo:5.0.14-focal
19 volumes:
20 - .volumes/db:/data/db
21 # WARNING: Exposing the database port will make it accessible from outside the container,
22 # potentially allowing unauthorized access. If you uncomment the ports below,
23 # ensure to secure your database (e.g., with strong authentication, proper network rules, and firewalls).
24 # ports:
25 # - 27017:27017
26 networks:
27 - internal
28 otel-collector:
29 image: ${HDX_IMAGE_REPO}/${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
30 environment:
31 CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s'
32 HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
33 HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
34 OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
35 ports:
36 - '13133:13133' # health_check extension
37 - '24225:24225' # fluentd receiver
38 - '4317:4317' # OTLP gRPC receiver
39 - '4318:4318' # OTLP http receiver
40 - '8888:8888' # metrics extension
41 restart: always
42 networks:
43 - internal
44 depends_on:
45 - ch-server
46 app:
47 image: ${HDX_IMAGE_REPO}/${IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
48 ports:
49 - ${HYPERDX_API_PORT}:${HYPERDX_API_PORT}
50 - ${HYPERDX_APP_PORT}:${HYPERDX_APP_PORT}
51 environment:
52 FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
53 HYPERDX_API_KEY: ${HYPERDX_API_KEY}
54 HYPERDX_API_PORT: ${HYPERDX_API_PORT}
55 HYPERDX_APP_PORT: ${HYPERDX_APP_PORT}
56 HYPERDX_APP_URL: ${HYPERDX_APP_URL}
57 HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
58 MINER_API_URL: 'http://miner:5123'
59 MONGO_URI: 'mongodb://db:27017/hyperdx'
60 NEXT_PUBLIC_SERVER_URL: http://127.0.0.1:${HYPERDX_API_PORT}
61 OPAMP_PORT: ${HYPERDX_OPAMP_PORT}
62 OTEL_SERVICE_NAME: 'hdx-oss-api'
63 USAGE_STATS_ENABLED: ${USAGE_STATS_ENABLED:-true}
64 DEFAULT_CONNECTIONS:
65 '[{"name":"Local
66 ClickHouse","host":"http://ch-server:8123","username":"default","password":""}]'
67 DEFAULT_SOURCES:
68 '[{"from":{"databaseName":"default","tableName":"otel_logs"},"kind":"log","timestampValueExpression":"TimestampTime","name":"Logs","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"Body","serviceNameExpression":"ServiceName","bodyExpression":"Body","eventAttributesExpression":"LogAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,SeverityText,Body","severityTextExpression":"SeverityText","traceIdExpression":"TraceId","spanIdExpression":"SpanId","connection":"Local
69 ClickHouse","traceSourceId":"Traces","sessionSourceId":"Sessions","metricSourceId":"Metrics"},{"from":{"databaseName":"default","tableName":"otel_traces"},"kind":"trace","timestampValueExpression":"Timestamp","name":"Traces","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"SpanName","serviceNameExpression":"ServiceName","bodyExpression":"SpanName","eventAttributesExpression":"SpanAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,StatusCode,round(Duration/1e6),SpanName","traceIdExpression":"TraceId","spanIdExpression":"SpanId","durationExpression":"Duration","durationPrecision":9,"parentSpanIdExpression":"ParentSpanId","spanNameExpression":"SpanName","spanKindExpression":"SpanKind","statusCodeExpression":"StatusCode","statusMessageExpression":"StatusMessage","connection":"Local
70 ClickHouse","logSourceId":"Logs","sessionSourceId":"Sessions","metricSourceId":"Metrics"},{"from":{"databaseName":"default","tableName":""},"kind":"metric","timestampValueExpression":"TimeUnix","name":"Metrics","resourceAttributesExpression":"ResourceAttributes","metricTables":{"gauge":"otel_metrics_gauge","histogram":"otel_metrics_histogram","sum":"otel_metrics_sum","_id":"682586a8b1f81924e628e808","id":"682586a8b1f81924e628e808"},"connection":"Local
71 ClickHouse","logSourceId":"Logs","traceSourceId":"Traces","sessionSourceId":"Sessions"},{"from":{"databaseName":"default","tableName":"hyperdx_sessions"},"kind":"session","timestampValueExpression":"TimestampTime","name":"Sessions","displayedTimestampValueExpression":"Timestamp","implicitColumnExpression":"Body","serviceNameExpression":"ServiceName","bodyExpression":"Body","eventAttributesExpression":"LogAttributes","resourceAttributesExpression":"ResourceAttributes","defaultTableSelectExpression":"Timestamp,ServiceName,SeverityText,Body","severityTextExpression":"SeverityText","traceIdExpression":"TraceId","spanIdExpression":"SpanId","connection":"Local
72 ClickHouse","logSourceId":"Logs","traceSourceId":"Traces","metricSourceId":"Metrics"}]'
73 networks:
74 - internal
75 depends_on:
76 - ch-server
77 - db
78 ch-server:
79 image: clickhouse/clickhouse-server:24-alpine
80 # WARNING: Exposing the database port will make it accessible from outside the container,
81 # potentially allowing unauthorized access. If you uncomment the ports below,
82 # ensure to secure your database (e.g., with strong authentication, proper network rules, and firewalls).
83 ports:
84 - 8123:8123 # http api
85 - 9050:9000 # native
86 # environment:
87 # default settings
88 # CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
89 volumes:
90 - ./docker/clickhouse/local/config.xml:/etc/clickhouse-server/config.xml
91 - ./docker/clickhouse/local/users.xml:/etc/clickhouse-server/users.xml
92 - ./empty.xml:/etc/clickhouse-server/users.d/default-password.xml
93 - .volumes/ch_data:/var/lib/clickhouse
94 - .volumes/ch_logs:/var/log/clickhouse-server
95 restart: on-failure
96 networks:
97 - internal
98networks:
99 internal:

注意：environment 部分我注释掉了，另外加了一行：./empty.xml:/etc/clickhouse-server/users.d/default-password.xml 作用是解决 clickhouse 连接异常的问题。

通过 /data/clickhouse/hyperdx/docker/clickhouse/local/users.xml 可以看到 clickhouse 的账户信息：

 1<?xml version="1.0"?>
 2<clickhouse>
 3 <profiles>
 4 <default>
 5 <max_memory_usage>10000000000</max_memory_usage>
 6 <use_uncompressed_cache>0</use_uncompressed_cache>
 7 <load_balancing>in_order</load_balancing>
 8 <log_queries>1</log_queries>
 9 </default>
10 </profiles>
11
12 <users>
13 <default>
14 <password_sha256_hex>2d964690ad5ac2d2f78bebadc30895bc519969ffcef4d3c9e7ff04ee1c765d96</password_sha256_hex>
15 <profile>default</profile>
16 <networks>
17 <ip>::/0</ip>
18 </networks>
19 <quota>default</quota>
20 </default>
21 <api>
22 <password>api</password>
23 <profile>default</profile>
24 <networks>
25 <ip>::/0</ip>
26 </networks>
27 <quota>default</quota>
28 </api>
29 <worker>
30 <password>worker</password>
31 <profile>default</profile>
32 <networks>
33 <ip>::/0</ip>
34 </networks>
35 <quota>default</quota>
36 </worker>
37 </users>
38
39 <quotas>
40 <default>
41 <interval>
42 <duration>3600</duration>
43 <queries>0</queries>
44 <errors>0</errors>
45 <result_rows>0</result_rows>
46 <read_rows>0</read_rows>
47 <execution_time>0</execution_time>
48 </interval>
49 </default>
50 </quotas>
51</clickhouse>

密码用 sha256sum 处理过

可以这样生成：

1echo -n '你的密码' | sha256sum

运行

点击登录跳转至首页

客户端连接

用户名：default
密码：你的密码
端口：8123

数据库初始化

初始化 sql 脚本

 1/* 1. 创建数据库（如已存在可先 DROP DATABASE IF EXISTS testdb） */
 2CREATE DATABASE IF NOT EXISTS testdb;
 3
 4/* 2. 维度表：用户 */
 5CREATE TABLE IF NOT EXISTS testdb.users (
 6 user_id UInt32,
 7 user_name String,
 8 signup_date Date
 9) ENGINE = MergeTree
10ORDER BY user_id;
11
12/* 3. 维度表：页面 */
13CREATE TABLE IF NOT EXISTS testdb.pages (
14 page_id UInt32,
15 page_url String,
16 category String
17) ENGINE = MergeTree
18ORDER BY page_id;
19
20/* 4. 事实表：页面访问日志 */
21CREATE TABLE IF NOT EXISTS testdb.pageviews (
22 event_date Date,
23 event_time DateTime,
24 user_id UInt32,
25 page_id UInt32,
26 duration UInt32 -- 停留秒数
27) ENGINE = MergeTree
28PARTITION BY toYYYYMM(event_date)
29ORDER BY (event_date, user_id, page_id);
30
31/* 5. 物化视图：每日 PV / UV 聚合 */
32CREATE MATERIALIZED VIEW IF NOT EXISTS testdb.pv_uv_daily
33ENGINE = SummingMergeTree
34PARTITION BY toYYYYMM(event_date)
35ORDER BY event_date
36AS
37SELECT
38 event_date,
39 count() AS pv,
40 uniqExact(user_id) AS uv
41FROM testdb.pageviews
42GROUP BY event_date;
43
44/* 6. 演示数据插入 ---------------------------------------- */
45
46/* 用户维度 */
47INSERT INTO testdb.users (user_id, user_name, signup_date) VALUES
48 (1, 'Alice', '2024-06-01'),
49 (2, 'Bob', '2024-07-15'),
50 (3, 'Cathy', '2024-11-30');
51
52/* 页面维度 */
53INSERT INTO testdb.pages (page_id, page_url, category) VALUES
54 (10, '/home', 'landing'),
55 (11, '/pricing', 'info'),
56 (12, '/blog', 'content');
57
58/* 页面访问日志 */
59INSERT INTO testdb.pageviews (event_date, event_time, user_id, page_id, duration) VALUES
60 ('2025-07-13', '2025-07-13 09:17:00', 1, 10, 35),
61 ('2025-07-13', '2025-07-13 09:18:07', 1, 11, 50),
62 ('2025-07-13', '2025-07-13 09:19:02', 2, 10, 15),
63 ('2025-07-14', '2025-07-14 10:03:45', 3, 12, 120),
64 ('2025-07-14', '2025-07-14 10:05:22', 1, 12, 90);
65
66/* 7. 快速验证 --------------------------------------------- */
67
68/* 查看当前数据库已创建的表 */
69SHOW TABLES FROM testdb;
70
71/* 查询物化视图结果 */
72SELECT * FROM testdb.pv_uv_daily ORDER BY event_date;
73
74/* 联表查询示例 */
75SELECT
76 u.user_name,
77 p.page_url,
78 v.event_time,
79 v.duration
80FROM testdb.pageviews AS v
81LEFT JOIN testdb.users AS u ON v.user_id = u.user_id
82LEFT JOIN testdb.pages AS p ON v.page_id = p.page_id
83ORDER BY v.event_time DESC;

从初始化一个现代 python 项目中学习到的东西

Sun, 27 Apr 2025 06:57:05 +0000

uv

我准备用 uv 初始化一个 python 项目

环境

我用的是苹果笔记本 MacBookPro ，具体的操作系统及硬件参数如下：

uv 的介绍与安装

“

uv 是一个使用 Rust 编写的工具，可以用来替代 pip、pipenv、pipx、poetry、virtualenv 等工具的使用，甚至还可以用来管理系统中所安装的 Python 发行版。uv 借鉴了很多现代语言中对于项目依赖的管理方式，项目中对于依赖的管理要远远优于使用 pip 和requirements.txt的方式。

我之前用过 pip 、pipx 等工具，发现 uv 确实要快不少。具体有多快呢？ github 上有个图：

🚀速度比传统 pip 快 10-100倍。

根据官网的介绍，uv 主要支持以下功能：

支持版本锁定的项目依赖管理。
支持直接运行 Python 脚本。
支持对系统中安装的 Python 进行管理，支持多版本 Python 共存。
支持 Python 包的发布和安装。
支持兼容 pip 的应用接口。
支持 Cargo 模式的项目工作区管理。
更优化的全局支持库缓存。
运行无需 Rust 或者 Python 支持。
支持 Windows、macOS 和 Linux 系统

uv 对多 python 版本和环境的管理很不错，这样你就可以一个项目指定一个特定的 Python 版本，放心使用，想怎么折腾怎么折腾，不会影响全局。

最近比较火的 MCP 很多也是用 uv 运行的，因为用 uv 命令可以直接运行 python 脚本。

uv 的安装非常简单：

1# macOS和Linux
2curl -LsSf https://astral.sh/uv/install.sh | sh
3
4# Windows PowerShell
5powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv 对 Python 的环境管理

首先用 uv 管理一下我们本机安装的 Python 环境。即到底安装了几个、哪些版本的 python。

可以用 uv python list 查看，像这样：

可以看到我已经安装了多个版本的 python。在后面建项目的时候，我选用 3.13 这个版本。当然你也可以根据你的情况下载新的需要使用的版本。这里给出一组相关命令：

1uv python install，安装指定版本的 Python。
2uv python list，列出系统中当前已经安装的 Python 版本。
3uv python find，查找一个已经安装的 Python 版本。
4uv python pin，固定当前项目使用指定的 Python 版本。
5uv python uninstall，卸载指定版本的 Python。

比如我要安装 3.12 这个版本，我就可以这样：

1uv python install 3.13

装好了不想要了，就可以这样卸载掉它：

1uv python uninstall 3.13

uv 进行项目管理

python 的环境有了以后，我们就可以新建项目了，建项目的时候也要用 uv 来进行初始化。

“

uv 的项目管理功能更多的借鉴了 Rust 中 Cargo 工具的项目管理理念。但主要区别是 uv 是通过项目目录中的pyproject.toml文件来完成项目管理的。

1uv init myproject

初始化后会生成以下几个文件：

虽然 uv init myproject 会帮你创建项目目录和 pyproject.toml，但默认不会自动创建虚拟环境（env），所以我们需要手动创建。

1# 手动创建虚拟环境
2uv venv --python 3.13
3# 激活虚拟环境
4source .venv/bin/activate

虚拟环境激活后，项目中会多一个.venv 文件夹。

接下来我们要自己创建一下源码目录和测试目录：

1mkdir -p src tests

到这里工程的相关目录我们就先到此为止，基本上创建完了，然后我们来编辑

pyproject.toml 配置文件。

toml 配置文件

我们先介绍一下 toml 文件，可能有些朋友不怎么了解它，比如搞 java 开发的。

TOML（Tom’s Obvious, Minimal Language）是一种配置文件格式，设计目标是易读、易写、易于解析，非常适合作为程序的配置语言，尤其是在现代的跨平台开发中被广泛采用。

你看这名字是不是觉得肯定跟 Tom 大哥有关系？

对，因为 TOML 由 GitHub 联合创始人 Tom Preston-Werner 在 2013 年发起，用以替代 JSON、INI 等配置格式在可读性和灵活性上的不足。

不过吧，后来这大哥（和她媳妇）不在 GitHub 干了，因为他们的一些不光彩的行为。具体是什么就不多说了，想八卦一下的可以去查查。

toml 配置文件用途广泛，常用于以下场景：

应用程序运行时配置
包管理工具（如 Python 的 pyproject.toml、Rust 的 Cargo.toml）
构建工具配置（如 poetry.toml, uv.toml）
数据库或服务连接信息等环境参数配置

举个例子吧：

 1# 数据库配置
 2[database]
 3server = "192.168.1.1"
 4ports = [ 8001, 8001, 8002 ]
 5enabled = true
 6
 7# 应用信息
 8[app]
 9name = "MyApp"
10version = "1.0.0"
11release_date = 2025-04-25T12:00:00Z

TOML 的特点可以总结为：

“

“比 JSON 更适合人读，比 YAML 更适合程序解析。”

它已经成为现代软件开发中最流行的配置文件格式之一，特别是在需要 清晰结构 + 丰富类型 + 可维护性 的场景中表现出色。

常见语言的支持情况：

Python：tomli / toml / pytoml / tomllib（Python 3.11 原生支持）
Rust：官方包管理工具 Cargo 就使用 TOML 格式的 Cargo.toml
Go：支持 BurntSushi/toml 库
Node.js：支持 @iarna/toml 等多个库

常见用途：

Python 包管理：pyproject.toml（PEP 518 标准）
Rust 项目管理：Cargo.toml
Web 项目配置：netlify.toml
DevOps 工具：例如 uv 的配置也是用 toml 文件

TOML 与其他格式的对比：

特性	TOML	JSON	YAML	INI
可读性	✅ 高	中	中高（但复杂）	中
注释支持	✅ 支持	❌ 不支持	✅ 支持	✅ 支持
数据类型支持	✅ 多	✅ 多	✅ 多	❌ 有限
库支持	✅ 常见语言皆支持	✅ 全面	✅ 全面	✅ 较好
学习曲线	✅ 低	✅ 低	❌ 偏高	✅ 极低

你看，TOML 作为配置文件感觉很不错对吧。

我们关于 TOML 的介绍就到此为止，现在来说一下我们这个初始化的新项目中的 pyproject.toml 文件要写成什么样。

就这样：

 1[build-system]
 2requires = ["hatchling"]
 3build-backend = "hatchling.build"
 4
 5[project]
 6name = "myproject"
 7version = "0.1.0"
 8description = "一个基于Python 3.13.3的项目"
 9readme = "README.md"
10requires-python = ">=3.13"
11authors = [
12 {name = "xiaobox", email = "xiaobox@gmail.com"}
13]
14dependencies = [
15 "pytest>=7.4.3",
16 "fastapi>=0.110.0",
17 "uvicorn>=0.27.0",
18 "httpx>=0.27.0",
19]
20classifiers = [
21 "Programming Language :: Python :: 3.13",
22 "License :: OSI Approved :: MIT License",
23 "Operating System :: OS Independent",
24]
25
26[project.scripts]
27myproject = "src.main:main"
28
29[project.urls]
30"Homepage" = "https://github.com/yourusername/myproject"
31"Bug Tracker" = "https://github.com/yourusername/myproject/issues"
32
33[project.optional-dependencies]
34dev = [
35 "black>=23.1.0",
36 "isort>=5.12.0",
37 "mypy>=1.5.1",
38]
39
40[tool.pytest]
41testpaths = ["tests"]
42
43[tool.black]
44line-length = 88
45target-version = ["py313"]
46
47[tool.isort]
48profile = "black"
49line_length = 88
50
51[tool.hatch.build.targets.wheel]
52packages = ["src"]

别小看了这个文件，它可是一个使用了 Hatch 构建工具、遵循 PEP 621 和现代 Python 项目结构规范的项目配置，涵盖了运行依赖、开发依赖、CLI 脚本、格式化工具配置、测试路径和打包目标，非常完整规范。

所以我们得逐行解释一下这个重要的文件。

toml 配置文件的逐行解释

我们上面的配置文件是一个标准的 Python 项目使用 pyproject.toml 来管理构建系统、依赖、工具配置的典型示例。下面我们来拆解和解释一下。

✅ [build-system]：构建系统配置（PEP 517 标准）

1[build-system]
2requires = ["hatchling"]
3build-backend = "hatchling.build"

requires：构建该项目所需的构建工具，这里是 hatchling，必须先安装。
build-backend：指定用哪个构建后端来执行打包任务，这里是 hatchling.build。

hatchling 有点儿类似 java 中的 Maven 或 Gradle，都是用来执行自动化构建流程的。

Maven 是把 java 代码编译、构建成 jar 包，方便管理依赖、分发、版本控制
hatchling 是把 python 代码构建成 Wheel（.whl 文件）或 Source Distribution（.tar.gz 或 .zip 文件），也是为了做依赖管理、分发和版本控制。

总结来说：Python 的构建是将代码和依赖打包成 .whl 或 .tar.gz，类似于 Java 打包成 .jar。核心目的是简化分发、确保环境一致性、自动化依赖管理。

✅ [project]：项目的核心元信息（PEP 621 标准）

1[project]
2name = "myproject"

项目名称，最终发布到 PyPI 时会用这个名字。

1version = "0.1.0"

当前版本号。

1description = "一个基于Python 3.13.3的项目"

简短的项目说明。

1readme = "README.md"

指定项目的 README 文件，将作为 PyPI 上项目首页的介绍内容。

1requires-python = ">=3.13"

要求的 Python 版本最低为 3.13。

1authors = [
2 {name = "xiaobox", email = "xiaobox@gmail.com"}
3]

作者信息，支持多个，用列表表示。

1dependencies = [
2 "pytest>=7.4.3",
3 "fastapi>=0.110.0",
4 "uvicorn>=0.27.0",
5 "httpx>=0.27.0",
6]

项目的运行时依赖库，在安装时会自动安装这些包。这里我加入了 pytest、fastapi 的依赖，因为我想把这个项目作为一个 api 服务提供出去。

1classifiers = [
2 "Programming Language :: Python :: 3.13",
3 "License :: OSI Approved :: MIT License",
4 "Operating System :: OS Independent",
5]

用于 PyPI 分类（帮助搜索和筛选）。

✅ `[project.scripts]`：定义可执行命令（如 CLI）

1[project.scripts]
2myproject = "src.main:main"

安装后运行 myproject 命令会调用 src/main.py 中的 main() 函数。（我们需要提前把之前的 main.py 文件要先移动到 /src 目录下）

✅ `[project.urls]`：项目的相关链接（非必须）

1[project.urls]
2"Homepage" = "https://github.com/yourusername/myproject"
3"Bug Tracker" = "https://github.com/yourusername/myproject/issues"

为项目指定一些有用的链接，如主页、问题反馈页等。

✅ `[project.optional-dependencies]`：可选依赖（比如开发环境）

1[project.optional-dependencies]
2dev = [
3 "black>=23.1.0",
4 "isort>=5.12.0",
5 "mypy>=1.5.1",
6]

我们为开发环境安装了三个库：black、isort 和 mypy

介绍一下这三个工具

black：是一个 Python 代码格式化工具。自动把你的 Python 代码排版成统一风格，比如：缩进、换行、空格都按标准格式处理，让你的 Python 代码看起来更整齐、统一，无需自己动手排版。
isort：是一个 Python 导入（import）语句自动排序工具。自动整理文件顶部的 import 语句，比如按字母顺序排列，分组标准库、第三方库、自定义模块，保持导入部分有序且规范。
mypy：是一个 Python 静态类型检查工具。检查你的代码里的类型注解（type hints）是不是正确，比如函数参数和返回值类型对不对，帮你在写代码时发现类型出错的地方，提前避免 bug。

✅ `[tool.pytest]`：Pytest 配置

1[tool.pytest]
2testpaths = ["tests"]

指定测试用例所在路径，pytest 会从 tests/ 目录开始查找测试文件。

✅ `[tool.black]`：代码格式化工具 Black 的配置

1[tool.black]
2line-length = 88
3target-version = ["py313"]

设置代码的行最大长度为 88（默认值），目标 Python 版本是 3.13。

✅ `[tool.isort]`：import 排序工具 isort 的配置

1[tool.isort]
2profile = "black"
3line_length = 88

使用 black 的风格对 import 排序。
设置行长度为 88，与 black 保持一致。

✅ `[tool.hatch.build.targets.wheel]`：Hatchling 打包配置

1[tool.hatch.build.targets.wheel]
2packages = ["src"]

指定打包时要包含的代码目录为 src。

用一句话总结下这个 pyproject.toml 配置文件：

“这是一个使用 Hatch 构建工具、遵循 PEP 621 和现代 Python 项目结构规范的项目配置，涵盖了运行依赖、开发依赖、CLI 脚本、格式化工具配置、测试路径和打包目标，非常完整规范。”

安装和更新依赖

上面这个文件编辑完成后，我们就可以安装项目和开发依赖了：

1uv pip install -e ".[dev]"

如果后面你更新了 pyproject.toml 文件可以执行以下命令来 “手动刷新” 一个依赖库：

1uv sync --extra dev

加入 --extra dev 参数是因为 uv sync 默认只安装 [project.dependencies] 中列出的正式依赖。

不会自动安装 [project.optional-dependencies]（比如 dev 里面的 black、isort、mypy）

uv sync --extra dev 的意思是：除了正式依赖，还要把 [project.optional-dependencies.dev] 里的东西也同步上

uv.lock

当执行完 uv sync --extra dev ，安装好依赖好， uv 会在项目根路径生成一个 uv.lock 文件。uv.lock 是锁定依赖版本的文件。

它的作用是：把 pyproject.toml 里描述的依赖（比如 “fastapi>=0.110.0” 这样比较宽松的范围），具体锁定成明确、唯一的版本（比如 “fastapi==0.110.1”）。

这样，每次安装时，不管谁来安装（你自己、你的同事、你的服务器），大家安装的依赖版本都是一模一样的，不会因为小版本不同导致奇怪的 bug。

uv.lock 是自动生成、自动管理的。不需手动编辑。

其他

其他的，如 fastapi 相关的、打 docker 镜像部署什么的相对本文主题超纲了，就不在本文中过多描述了。

总结

本文我们分享了用 uv 初始化和管理 Python 项目的完整流程。

从安装 uv 开始，我介绍了它为什么比传统工具（pip、pipx、poetry 等）更快更好用，以及 uv 在多 Python 版本管理、依赖锁定、项目初始化方面带来的便利。

随后，详细讲了如何用 uv 管理本地 Python 环境、新建项目、创建虚拟环境、编辑 pyproject.toml 配置，并逐步解释了各个配置项的作用

整体来看，uv 提供了一套现代、规范、高效的 Python 项目管理方案，非常适合用来打基础，后续无论是开发 API、打包 Docker 镜像，还是部署上线，都能有条不紊地进行。

同时我们通过在项目创建的过程中看到各语言（java、nodejs…）都相通或类似的工程 “最佳实践”，真是应了那句话：“大道至简，真理趋同”

还在用 top htop? 赶紧换 btop 吧，真香！

Tue, 17 Sep 2024 03:35:33 +0000

top

在 Linux 服务器上，或类 Unix 的机器上，一般我们想查看每个进程的 CPU 使用率、内存使用情况以及其他相关信息时会使用 top 命令。

top 是一个标准的 Linux/Unix 工具，实际上我从一开始接触 Linux 就一直使用 top , 一般是两种场景：

Linux 服务器上用
自己的 Mac 电脑上用

top 有一些常用的功能，比如可以动态的显示进程的情况，按照 CPU 、内存使用率排序等。说实话，这么多年了，使用最多的还就是 top ，一来是因为习惯了，工具用惯了很多操作都是肌肉记忆。二来是 top 一般系统自带不用安装，省事儿。

htop

top 挺好的，但 top 对于初学者和小白用户不太友好，尤其是它的用户界面和操作。于是后来有了 htop

htop 是 top 的一个增强替代品，提供了更加友好的用户界面和更多的功能。与 top 相比，htop 默认以颜色区分不同的信息，并且支持水平滚动查看更多的进程信息。htop 还允许用户使用方向键来选择进程，并可以直接发送信号给进程（如 SIGKILL）。htop 支持多种视图和配置选项，使得用户可以根据自己的喜好定制显示的内容。

htop 我也用了几年，确实舒服一些，但由于需要安装和我对 top 的肌肉记忆，htop 在我的使用中并未完全替代 top。直到 btop 的出现

btop

现在，我本机使用的是 btop，有了 btop，top 和 htop 一点儿都不想用了，哈哈。

在服务器上有时候因为懒不想安装，一部分时间还是 top，一部分用 btop。

第一印象是真漂亮啊，然而它不止好看，功能也是很实用，操作还很简单，你说能不喜欢它吗？

说是 btop ，实际上人家真正的名字是 btop++ , 用 C++ 开发的

安装

btop 支持各种类 Unix 系统，你可以在它的文档中找到对应系统的安装方法 https://github.com/aristocratos/btop

本文演示，我是用我自己的 Mac 笔记本电脑，用 Mac 安装很简单，用 brew 一行搞定

brew install btop

我的系统情况是这样的：

安装完成后，直接运行 btop 就可以看到如上图的界面了。

功能界面

打开 btop 后不要被它的界面唬住了，其实非常的简单，我们来介绍一下。

打开 btop 后，其实显示的是它给你的 “预置” 界面。默认有 4 个预置界面，你可以按 p 键进行切换。命令行界面上会分别显示：

preset 0
preset 1
preset 2
preset 3

你可能注意到了，这 4 个预置界面中有很多内容是重复的，没错，其实 btop 一共就 4 个模块，预置界面只是把不同的模块拼在一起显示罢了。这 4 个模块分别是：

CPU 模块
存储模块
网络模块
进程模块

这 4 个模块对应的快捷键分别就是 1，2，3，4 你按一下模块显示，再按一下模块隐藏。

所以如果你对预置界面的内容想立刻调整，就可以按快捷键来显示/隐藏你想要的模块，当然预置界面也是可以通过配置文件调整的，这个我们后面说。

CPU 模块

CPU 模块可以显示 CPU 型号、各内核的使用率、温度，CPU 整体的负载，以及一个直观的图象，所有数据都是实时显示的。

存储模块

存储模块包括两部分，一个是内存使用情况，一个是磁盘使用情况：

因为比较直观，具体内容我就不解释了。

网络模块

网络模块可以看下网络的整体负载和吞吐情况，主要包括上行和下行数据汇总，你可以通过按快捷键 b和n 来切换看不同的网卡。

进程模块

初始的进程模块可以看到：

pid
Program: 进程名称
Command: 执行命令的路径
Threads: 进程包含的线程数
User: 启动进程的用户
MemB: 进程所占用内存
Cpu%: 进程所占用 CPU 百分比

你可以按快捷键 e 显示树状视图：

可以按快捷键 r 对进行排序，按一下是倒序，再按一下是正序。具体排序列可以按左右箭头，根据界面显示进行选择，比如我要按照内存使用排序，那么右上角就是这样的：

按 f 键输入你想过滤的内容然后回车，可以过滤一下界面显示的内容，比如我只想看 chrome 的进程情况：

还可以通过上下箭头选中某一个进程按回车查看进程详情，再次按回车可以隐藏详情：

显示进程详情后可以对进程进行操作，比如 Kill 只需要按快捷键 k 就可以了，然后会弹出提示：

主题

怎么样，是不是很方便，操作简单，上手容易，还好看。关于 btop 的主要操作就这些了，剩下的可以参考 help 和 menu 中显示的内容自行操作和设置都很简单。

btop 的配置文件默认在这里：$HOME/.config/btop ，你可以直接修改配置文件中的详细参数，如我们前文提到的 “预置” 界面以及预置界面内容都可以在配置文件中设置：

此外 btop 还有很多好看的主题配色，但默认安装的情况下只带了一个 Default 的，如果你想切换用其他的主题，需要先下载这些主题，主题文件在这里：https://github.com/aristocratos/btop/tree/main/themes

下载好以后放到本地对应的文件夹中 ~/.config/btop/themes

然后你就可以要界面上进行主题的切换了，具体流程是先按快捷键 m ，然后选 OPTIONS

接着在 Color theme 中就能看到你当前拥有的 theme 数据，按方向键就可以切换主题配色了：

主题有很多，我这里给大家一个完整的预览：

我目前使用的就是 Default 我觉得最符合我的审美。

最后

用了 btop 后你就再也回不去了，一般情况下再也不会想用 htop 和 top 了，大家没有换的可以直接换了

一文帮你解决 Linux 发行版 “选择困难症”

Thu, 12 Sep 2024 08:21:56 +0000

工作关系，今天要买一批云服务器。打开熟悉的阿里云，到选择操作系统这项的时候我停了下来，因为我发现现在的 linux 发行版是真多呀，阿里云默认显示的公共镜像就这么多：

10年前几乎闭眼选择 CentOS 的时代一去不复返了。那么到底应该选择哪个发行版呢？所以干脆写篇文章来盘点一下这些 linux 发行版

对了，你可能发现我直接忽略了 Windows Server ，是的，因为 90% 以上的服务器选择安装 linux 操作系统。

Linux 发行版和 Linux 内核之间的关系

先把最基本的概念弄清楚：

Linux 内核是操作系统的核心部分,由 Linus Torvalds 最初开发并持续维护。它负责管理硬件资源、提供系统调用等最基本的功能。
Linux 发行版是在 Linux 内核基础上,添加了各种系统软件、应用程序、配置工具等,组成的完整可用的操作系统。

发行版的主要工作是：1）选择特定版本的 Linux 内核、2）添加各种系统软件和应用程序、 3）开发独特的安装程序和系统管理工具 4）提供技术支持和更新

常见的发行版有 Ubuntu、Fedora、CentOS、Debian 等。所有 Linux 发行版都使用 Linux 内核作为核心,遵循 GNU 通用公共许可证。

流行的 Linux 发行版

排名不分先后，虽然前文上图中有阿里云的 Alibaba Cloud Linux 但因为云平台自身利益关系，它的排名和推广不代表流行程度，所以我这里忽略它。

Anolis OS

Anolis OS 可能没有其他发行版那么知名，它是是由阿里云开发，但 AnolisOS 仍然是开源的，遵循开源许可，所以我这里也要提一下，支持开源社区

“

Anolis OS 8 是 OpenAnolis 社区推出的完全开源、中立、开放的发行版，它支持多计算架构，也面向云端场景优化，兼容 CentOS 软件生态

简单说，AnolisOS 是基于 CentOS 进行的二次开发，所以如果你更熟悉 CentOS，又讨厌现在 RedHat 对 CentOS 的最新政策，那么可以试一试它。不过选择操作系统还是要谨慎，毕竟基础设施运维起来有坑的话都是大坑，哈哈。

CentOS

这个我们可得好好说说，可以说是大家最熟悉的 Linux 发行版了。为什么呢？

最初红帽公司开发了企业级付费的 linux 操作系统：Red Hat Enterprise Linux (RHEL)。CentOS 本身是 RHEL 的一个免费开源复制版。这对于广大开发者和系统使用者可是件大好事，因为有企业级付费产品冲在前线做质量保障，CentOS 直接跟在屁股后面复制成果做免费开源，当时的 Red Hat 简直是IT界的赛博菩萨。CentOS 也成为了很多公司服务器操作系统的不二之选。

然而：

“

CentOS 7已于2024年6月30日停止维护，CentOS官方已停止维护CentOS计划。

CentOS 没了？倒也不是，Red Hat 更新了产品策略。旧的 CentOS 确实不再维护了，不是不能用，是不再维护了，如果操作系统有bug 可没人管了哈。所以选择老版本的CentOS需要谨慎。

新版的 CentOS 叫 CentOS Stream ，别看就多了个 Stream，情况却大不一样。与之前的 RHEL 在前，CentOS 在后相比，这次 Red Hat是这么设计的：CentOS Stream 仍然开源，但它是在第一线的，而 RHEL这次反过来是在 CentOS Stream的后面享受开源的成果。说白了，让社区的开发给 CentOS Stream 提feature 改 bug，RHEL 在后面积累成果卖钱。让大家给 Red Hat 打工。

总结来说：

原来 Centos 是 RHEL 的下游复制品。CentOS（在转变前）紧跟 RHEL 的发布节奏
现在 CentOS Stream 是 RHEL的上游产品。

当然工也不是白打，你不也用人家的操作系统了嘛。

相比前后两种策略，大家心里跟明镜似的，越来越多的人不再选择 CentOS 了，虽然出了bug 有社区维护，但相比之前有个靠谱商业付费产品做基础，保障少多了，担心多多了。运维也不想加班呀。

事情发展到这里还没有结束，因为大家不禁要问，CentOS 一直所坚持的开源精神呢？难道这精神没有继续者吗？

有！！

Gregory Kurtzer 站了出来。

CentOS 的原始创始人 Gregory Kurtzer 发起了 Rocky Linux 项目，目标是创建一个与 RHEL 100% 兼容的下游版本，旨在成为 CentOS 的精神继承者。

还有！！

AlmaLinux 由 CloudLinux 公司发起，同样旨在提供一个与 RHEL 完全兼容的免费替代品。

开源的精神没有覆灭，Rocky Linux 和 AlmaLinux 都是 RHEL 的下源产品，如果你想找到一个 CentOS 的替代品，那么这两个发行版可能会很适合你。

Red Hat Enterprise Linux

红帽公司著名产品：

前文多次提到它，收费，稳定，天下没有花钱的不是，一分钱一分货。但确实是贵啊（相比开源免费）。。。

SUSE Linux

又是一个和 RHEL 齐名的付费产品

但它开始的时候也是一个有志青年，是不收费的。

早期（1992-2003）：SUSE 最初是一个开源项目，提供免费版本。被 Novell 收购后，仍保留了开源版本 openSUSE。从 Novell 分离后，SUSE 成为独立公司，开始更注重商业模式。

现在，SUSE Linux Enterprise（SLE）是付费的企业版本。openSUSE 仍然是免费开源的社区版本。

SUSE 和 RHEL 在技术和使用上的区别挺多的，但我感觉最大的区别是 SUSE 在欧洲市场较强，特别是在 SAP 环境中。如果欧洲企业中有使用 OpenStack 和 SAP 的，那么愿意为操作系统付费的企业很可能选择的就是 SUSE。

Fedora

在 Fedora 7 之前，Fedora 的名字是“Fedora Core”，之后就简称为 Fedora

Fedora 是一个快速发展的、面向技术爱好者的 Linux 发行版。

Fedora 是 RHEL 的上游项目之一。RHEL 的开发团队会从 Fedora 社区中吸取一些新的特性和改进，然后根据企业的需要进行调整和完善。因此，可以说 Fedora 在某种程度上影响了 RHEL 的发展方向。看了前文的读者读到这里是不是已经熟悉 RedHat 的套路了？所以你在选择操作系统上也要掌握点儿 “反套路” 才行。

Debian

与 RHEL 不同，Debian 是纯社区驱动的项目。

Debian 有较长的发布周期，注重稳定性，这是它的优势也是劣势。较长的发布周期可能导致软件版本较旧。

Debian 稳定版通常包含较旧但经过充分测试的软件。但 Debian 对新手来说可能不够友好

可能最为人熟知的就是包管理系统

Debian 使用 APT（Advanced Package Tool）和 .deb 包格式。
CentOS 使用 YUM/DNF 和 .rpm 包格式。

Ubuntu

这个发行版大家也很熟悉，你看，一般大家比较熟悉的发行版做的都比较好，不然不会有那么多人喜欢它。

Ubuntu 是一个基于 Debian 的 Linux 发行版，由 Canonical Ltd. 公司维护和支持。我们上文刚才了 Debian的一些问题，比如发布周期长，对新手不友好等，Ubuntu 就有针对性的解决了这些问题：

“

Ubuntu 的目标是提供一个稳定、用户友好的操作系统，并且它特别注重易用性和社区支持。Ubuntu 每六个月发布一个新版本，其中每隔两年会有一个长期支持（LTS）版本，提供长达五年的安全更新和技术支持。

这里我们不禁要比较一下 Debian和 Ubuntu(我肯定选后者啦) ：Ubuntu 基于 Debian，因此两者共享许多软件包。然而，Debian 更加注重稳定性和安全性，更新周期更长；而 Ubuntu 则更注重易用性和最新技术的应用。

还是列举一下 Ubuntu的优缺点：

更新频繁，软件包较新
强大的社区支持
良好的桌面和服务器体验
丰富的文档和资源
与 RHEL 生态系统不兼容

现在，越来越多的运维同学选择 Ubuntu 作为服务器的操作系统，我觉得可能有这么几点原因：

Ubuntu 对各种硬件的支持非常广泛，这对于新的发行版来说是一个重要优势。
Ubuntu 在容器技术和云计算方面有很好的支持
Ubuntu 拥有庞大的用户和开发者社区，这意味着丰富的资源、文档和第三方支持。
Ubuntu 的六个月发布周期和长期支持版本（LTS）提供了良好的平衡，可以根据需要选择稳定性或新特性。
Ubuntu 的 APT 包管理系统强大且用户友好，便于管理和定制软件包。

总结

本文我们讨论了在购买云服务器时面临众多 Linux 发行版选择的问题。随着 CentOS 7 的停止维护以及 CentOS Stream 成为 RHEL 的上游版本，过去直接选择 CentOS 的做法已不再适用。我们提到了几个主要的 Linux 发行版，包括：

Anolis OS：阿里云开发的开源发行版，基于 CentOS 进行了二次开发，兼容 CentOS 生态。
CentOS：曾经作为 RHEL 的下游复制品，现已转变为 RHEL 的上游版本 CentOS Stream，不再作为 RHEL 的直接复制品。
Rocky Linux 和 AlmaLinux：作为 CentOS 的精神继承者，这两个发行版提供了与 RHEL 完全兼容的免费替代品。
Red Hat Enterprise Linux (RHEL)：商业化的 Linux 发行版，提供企业级支持和服务。
SUSE Linux：与 RHEL 类似的商业发行版，在欧洲市场尤其是 SAP 环境中较为流行。
Fedora：快速发展的发行版，作为 RHEL 的上游项目，为 RHEL 提供技术创新。
Debian：社区驱动的发行版，注重稳定性和安全性，但软件版本可能较旧。
Ubuntu：基于 Debian，注重易用性和最新技术的应用，每六个月发布一次新版本，并提供 LTS 版本。

最后我说一下我个人对 linux 发行版的选择排序：

Rocky Linux > Ubuntu > AlmaLinux > CentOS Stream

IP地址的多种书写方式

Fri, 30 Aug 2024 02:36:04 +0000

当我们提及 IP 地址，大多数人首先想到的是那种我们习以为常的形式：如 127.0.0.1、10.0.2.1 等。这些由数字和点组成的串，在日复一日的使用中，或许已经变得有些单调乏味。但你是否知道，IP 地址并非只能以这种方式呈现？事实上，它拥有多种书写方式，这些不同的形式不仅可以为我们带来乐趣，更能在某些特定场合发挥出意想不到的作用。

一、IP 地址的常规书写与潜在变化

在大多数情况下，我们使用的 IP 地址都是点分十进制格式，即由四个 0-255 之间的数字组成，数字之间用点号分隔。这种格式简单明了，易于理解和记忆。然而，这种常规的书写方式背后，其实隐藏着一些不为人知的秘密。

二、零的可选性

首先，让我们来看一个有趣的例子。

在 Linux 系统中，输入ping 0，你会发现它实际上被解析为127.0.0.1。

1$ ping 0
2PING 0 (127.0.0.1) 56(84) bytes of data.
364 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.053 ms
464 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.037 ms

但在 Mac 系统中，同样的命令却会返回一个错误，提示无法找到目标主机。

1$ ping 0
2PING 0 (0.0.0.0): 56 data bytes
3ping: sendto: No route to host

这是因为，在不同的操作系统中，对于 IP 地址中零的处理方式可能存在差异。

再来看另一个例子：ping 127.1。这个命令在大多数系统中会被解析为127.0.0.1，系统会自动在数字前补零。

1$ ping 127.1
2PING 127.1 (127.0.0.1): 56 data bytes
364 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.033 ms
464 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.085 ms

但请注意，这并不意味着计算机可以随意猜测并填充零。例如，ping 10.50.1会被解析为10.50.0.1，而不是10.50.1.0或其他形式。

1$ ping 10.50.1
2PING 10.50.1 (10.50.0.1): 56 data bytes
3Request timeout for icmp_seq 0

这是因为 IP 地址的结构是固定的，每个部分都有其特定的含义和范围。

三、IP 地址的“溢出”技巧

除了零的可选性外，我们还可以利用 IP 地址的“溢出”特性来玩一些小把戏。例如，ping 10.0.513这个命令，在大多数系统中会被解析为10.0.2.1。这是因为 IP 地址的每个部分都是一个 8 位的二进制数，最大值为 255。当超过这个值时，它会自动“溢出”并从零开始重新计数。在这个例子中，513 被解析为 2x256+1，即 257，但由于 IP 地址每部分的取值范围是 0-255，所以它实际上被解析为 2，再加上前面的 10.0.0，就得到了 10.0.2.1。

1$ ping 10.0.513
2PING 10.0.513 (10.0.2.1): 56 data bytes
364 bytes from 10.0.2.1: icmp_seq=0 ttl=61 time=10.189 ms
464 bytes from 10.0.2.1: icmp_seq=1 ttl=61 time=58.119 ms

这种“溢出”技巧不仅可以用于娱乐和恶作剧，还可以在某些特定场合发挥出实际作用。例如，在网络安全领域，攻击者可能会利用这种技巧来绕过一些基于 IP 地址的过滤和限制。

四、十进制、十六进制与八进制的 IP 表示

除了我们常见的点分十进制格式外，IP 地址还可以用其他进制来表示。例如，我们可以使用十进制数来表示一个 IP 地址。

1$ ping 167772673
2PING 167772673 (10.0.2.1): 56 data bytes
364 bytes from 10.0.2.1: icmp_seq=0 ttl=61 time=15.441 ms
464 bytes from 10.0.2.1: icmp_seq=1 ttl=61 time=4.627 ms

如上文提到的ping 167772673，这个十进制数实际上就是10.0.2.1的另一种表现形式。这种表示方法在某些编程和网络调试场景中可能会更加方便。

具体来说：167772673 在十进制下转换为二进制是 00001010000000000000001000000001

这个二进制数可以按照每 8 位一组分割为：

00001010
00000000
00000010
00000001

分别转换为十进制数为：

同样地，十六进制也是 IP 地址的一种常见表示方式。例如，ping 0xA000201这个命令中的0xA000201就是一个十六进制数，它同样表示的是10.0.2.1。在计算机科学中，十六进制是一种常用的表示方式，因为它可以更紧凑地表示较大的数字，并且与二进制之间的转换相对简单。

1$ ping 0xA000201
2PING 0xA000201 (10.0.2.1): 56 data bytes
364 bytes from 10.0.2.1: icmp_seq=0 ttl=61 time=7.329 ms
464 bytes from 10.0.2.1: icmp_seq=1 ttl=61 time=18.350 ms

此外，我们还可以使用八进制来表示 IP 地址。虽然这种方式在实际应用中相对较少见，但它同样具有一定的理论和实际意义。例如，ping 10.0.2.010这个命令中的.010实际上就是八进制数 8，所以这个命令最终会被解析为10.0.2.8。

1$ ping 10.0.2.010
2PING 10.0.2.010 (10.0.2.8): 56 data bytes

五、使用 Sipcalc 工具进行 IP 地址转换

对于需要进行大量 IP 地址转换的场景，我们可以借助一些工具来简化操作。其中，sipcalc （https://github.com/sii/sipcalc）就是一个非常实用的命令行 IP 地址计算器。它可以方便地进行十进制、十六进制等不同进制之间的转换，并且提供了丰富的输出格式和选项。

使用sipcalc工具，我们可以轻松地将一个 IP 地址从一种格式转换为另一种格式。例如，要将十进制数167772673转换为点分十进制格式，我们可以输入相应的命令并得到结果10.0.2.1。同样地，我们也可以将一个点分十进制格式的 IP 地址转换为其他进制表示形式。

六、IP 地址书写方式的多样性与应用场景

除了上述提到的几种 IP 地址书写方式外，还有一些其他不太常见但同样有趣的表示方法。这些方法或许在日常使用中并不常见，但在某些特定场合却能发挥出意想不到的作用。

例如，在网络安全领域，攻击者可能会利用 IP 地址的不同书写方式来绕过一些基于规则的过滤和检测系统。他们可能会使用一些特殊格式的 IP 地址来隐藏真实的攻击目标或规避安全策略。

此外，在网络编程和调试过程中，灵活运用 IP 地址的不同书写方式也可以为我们带来便利。例如，在编写网络应用程序时，我们可能需要根据不同的需求和环境选择最合适的 IP 地址表示形式。

七、如何防范 IP 地址欺骗与攻击

虽然 IP 地址的不同书写方式为我们带来了乐趣和便利，但与此同时也带来了一定的安全风险。特别是当攻击者利用这些技巧进行 IP 地址欺骗和攻击时，后果将不堪设想。

为了防范这些潜在的安全威胁，我们可以采取以下措施：

使用防火墙和安全策略：配置防火墙和安全策略来限制对特定 IP 地址或 IP 地址范围的访问。这样可以有效防止未经授权的访问和攻击。
验证 IP 地址来源：在进行网络通信和数据交换时，务必验证对方的 IP 地址来源和真实性。不要轻易相信来自未知或可疑来源的 IP 地址信息。
定期更新系统和软件：及时更新操作系统、应用程序和安全补丁以修复可能存在的安全漏洞。这样可以降低被攻击的风险并提高系统的安全性。
加强网络安全培训：提高员工和用户的网络安全意识培训，让他们了解常见的网络攻击手段和防范措施。这样可以形成一道坚实的网络安全防线。

八、结语

通过本文的介绍和分析，我们可以看到 IP 地址并非只能以常规的点分十进制格式呈现。除了这种常见形式外，它还可以用其他多种方式来表示和书写。这些不同的书写方式不仅为我们带来了乐趣和便利，更在某些特定场合发挥出意想不到的作用。

然而，与此同时我们也需要注意防范这些不同书写方式可能带来的安全风险。通过采取适当的安全措施和策略，我们可以有效降低潜在的安全威胁并保障网络安全。

最后，希望这篇文章能为你带来一些新的启示和思考。如果你对 IP 地址或其他网络安全话题感兴趣，欢迎继续关注和探索更多有趣的内容！

探索 multipart：文件传输的新境界！

Thu, 29 Aug 2024 09:11:45 +0000

HTTP Multipart 介绍

在日常的网络编程和数据传输中，我们经常会遇到“multipart”或“form-encoded data”这样的术语。尽管这些术语在我日常工作中随处可见，但我却从未真正深入理解或使用过它们，因为 HTTP 库已经为我处理好了这些细节。然而，最近由于在工作中的需求，我不得不深入研究 multipart 的工作原理。我发现，正确地使用 multipart 可以显著提高文件上传的速度并减少内存消耗。接下来，我将详细解释 multipart 的工作原理，希望能帮助你在 HTTP 服务器/客户端中节省时间和内存。

一、什么是 MIME 类型？

在深入探讨 multipart 之前，我们需要先了解什么是 MIME 类型。MIME（Multipurpose Internet Mail Extensions）是一种标准，用于描述文档的性质和格式。简单来说，MIME 类型就是文件的“身份证”，它告诉计算机这个文件是什么类型的，应该用什么样的程序来打开。例如，常见的 MIME 类型有text/plain（纯文本）、image/jpeg（JPEG 图片）和application/pdf（PDF 文档）等。

二、为什么需要使用 Multipart？

在 multipart 出现之前，上传文件的标准是application/x-www-form-urlencoded。这种方式要求客户端在上传文件之前对其进行 URL 编码。如果文件主要是 ASCII 文本，URL 编码是高效的；但如果文件主要是二进制数据，那么几乎每个字节都需要进行 URL 转义，这会非常低效。

如果你想上传多个文件而不进行编码，你可以发送多个 HTTP 请求。但这样做的延迟会比在一个请求中发送所有文件更高。为了解决这个问题，1998 年的 RFC 2388 提出了一个新的标准——“multipart/form-data”。这个标准允许你在一个 HTTP 正文中发送多个文件，而无需对它们进行编码。无需编码意味着你可以节省大量的 CPU 周期，并保持总体正文大小较小。

这个协议最初是为从 HTML 表单上传文件而设计的，因此得名。但实际上，你可以使用它从任何你想要的地方上传文件——规范中没有任何部分要求<form>或任何 HTML。你可以使用它从任何 HTTP 客户端向任何 HTTP 服务器上传文件。

当你上传文件时，如果你把文件打包成一个 JSON 对象，服务器需要先接收整个 JSON 对象，然后才能开始处理。这样会占用更多内存，而且要等所有文件都上传完毕才能开始处理。

 1import json
 2import requests
 3
 4# 读取多个文件内容
 5files = ['file1.txt', 'file2.txt', 'file3.txt']
 6file_contents = {}
 7
 8for file_name in files:
 9 with open(file_name, 'r') as file:
10 file_contents[file_name] = file.read()
11
12# 将文件内容打包成 JSON 对象
13data = {
14 'files': file_contents
15}
16
17# 将 JSON 对象转换为字符串
18json_data = json.dumps(data)
19
20# 上传 JSON 对象到服务器
21response = requests.post('http://example.com/upload', data=json_data, headers={'Content-Type': 'application/json'})
22
23print(response.status_code)

JSON 格式不支持直接在数据结构中嵌入二进制数据（如图片、视频文件等）。由于 JSON 不能直接包含二进制数据，所以如果你想要通过 JSON 格式来上传一个图片或视频文件，你就需要将这个二进制文件转换成一种可以被 JSON 处理的格式。Base64 就是这样一种格式。

如果你使用 multipart 格式上传，服务器可以一个接一个地接收文件，就像流水一样。这意味着服务器可以更早开始处理第一个文件，而不需要等待其他文件，这样更节省内存，速度也更快。

 1<!DOCTYPE html>
 2<html>
 3<head>
 4 <title>Multipart Upload Example</title>
 5</head>
 6<body>
 7 <form action="/upload" method="post" enctype="multipart/form-data">
 8 <input type="file" name="file1" multiple>
 9 <input type="file" name="file2" multiple>
10 <input type="submit" value="Upload">
11 </form>
12</body>
13</html>
14
15from flask import Flask, request
16
17app = Flask(__name__)
18
19@app.route('/upload', methods=['POST'])
20def upload_files():
21 # 获取名为 file1 和 file2 的文件
22 file1 = request.files.get('file1')
23 file2 = request.files.get('file2')
24
25 if file1:
26 # 处理 file1
27 process_file(file1)
28 
29 if file2:
30 # 处理 file2
31 process_file(file2)
32
33 return "Files processed successfully!"
34
35def process_file(file):
36 # 这里是处理文件的地方
37 # 可以将文件保存到磁盘或其他操作
38 file.save(file.filename)
39
40if __name__ == '__main__':
41 app.run(debug=True)

三、Multipart 是什么？

MIME 类型分为两类：离散型和多部分型。离散型包含一个文档，例如application/（二进制）、image/、text/等。多部分型是包含多个部分的文档，这些部分可以有自己的 MIME 类型。有两种多部分类型：message/和multipart/——是的，有点让人困惑，multipart 既可以是一种类型，也可以是一个类别。message/类型基本上不再用于任何东西了，但multipart/仍然非常重要。你经常看到multipart/form-data用于通过 HTML 表单从 Web 浏览器发送文件到服务器。multipart 中的“part”指的是一个文档。这个类型本可以叫做multidocument！

需要注意的是，它并不一定要包含多个文件。它可以只包含一个文件，使用 multipart 进行高效的二进制编码。

四、Multipart 是如何实现的？

如果内容类型是multipart/form-data，那么 HTTP 正文中包含多个部分（即文档）。每个部分由一个“边界分隔符”分隔。根 HTTP 消息有一个头部定义了边界分隔符，以便服务器知道每个部分之间的边界在哪里。每个部分也有一些头部：

Content-Disposition头部定义了每个部分的文件名或包含它的表单字段的名称（仅当你使用实际的 HTML 表单元素时才相关）。
Content-Type头部定义了每个部分的文件类型（技术上是它们的 MIME 类型，但这两者大致相当）。它默认为text/plain。非结构化二进制数据应使用application/octet-stream，但如果你知道类型，你应该使用例如application/zip、application/pdf等。

其他头部不能使用！根据 RFC 7578 的说法：“multipart/form-data媒体类型不支持除Content-Type、Content-Disposition和（在有限情况下）Content-Transfer-Encoding之外的任何 MIME 头部字段。其他头部字段不得包含且必须被忽略。”

以下是一个来自 Stack Overflow 的实际示例，展示了 HTTP 正文的样子。这个正文是一个包含 3 个 GIF 的多部分。

 1POST /cgi-bin/qtest HTTP/1.1
 2Content-Type: multipart/form-data; boundary=2a8ae6ad-f4ad-4d9a-a92c-6d217011fe0f
 3Content-Length: 514
 4
 5--2a8ae6ad-f4ad-4d9a-a92c-6d217011fe0f
 6Content-Disposition: form-data; name="datafile1"; filename="r.gif"
 7Content-Type: image/gif
 8GIF87a.D..;
 9--2a8ae6ad-f4ad-4d9a-a92c-6d217011fe0f
10Content-Disposition: form-data; name="datafile2"; filename="g.gif"
11Content-Type: image/gif
12GIF87a.D..;
13--2a8ae6ad-f4ad-4d9a-a92c-6d217011fe0f
14Content-Disposition: form-data; name="datafile3"; filename="b.gif"
15Content-Type: image/gif
16GIF87a.D..;
17--2a8ae6ad-f4ad-4d9a-a92c-6d217011fe0f--

五、压缩

你可以对整个 Multipart 响应进行 gzip 压缩，但不能选择性地压缩特定部分。这是因为根 HTTP 正文定义了整个消息的压缩头部，包括 multipart 正文中的所有部分。因此，客户端无法告诉服务器“这个特定部分是压缩的，但那个不是”。

如上所述，multipart 的文档中只允许使用 3 个特定的 HTTP 头部——而压缩头部不是其中之一。

六、为什么这很有趣？

所以，“multipart”或“form-encoded data”是一种包含多个文件的 MIME 类型。每个文件都有自己的 MIME 类型和名称。从历史上看，这比上传多个文件的其他方式是一个很大的改进，因为它可以发送原始二进制文件而无需额外的编码或转义。

在我写这篇博客文章之前，我觉得 multipart 有点无聊。它似乎有点过时和落后——我的意思是，它是在 HTML 表单是 Web 技术的前沿时编写的。自从它的 RFC 首次发布以来已经有 25 年了。我们肯定有更好的上传文件的方法了！

但实际上，这在抽象意义上是相当有趣的。它试图有效地组合多个文件上传，而“我们如何将许多文件组合在一起”的问题在计算机科学中总是一个有趣的问题。我喜欢 JSON 的原因之一是它很容易组合。如果每个文件上传是一个 JSON 正文，那么组合它们是微不足道的：只需将 n 个单独的 JSON 正文组合成一个包含 n 个字段的大正文。

但这性能不佳：你必须将文件内容 base64 编码，因为 JSON 只能处理文本，不能处理二进制；服务器必须将整个 JSON 正文缓冲到 RAM 中才能解码。

我认为multipart/form-data是试图有效地组合多个文件上传的一种尝试。这种权衡带来了一些复杂性，比如边界和内容处置。我想知道现代解决这个问题的方案会是什么样子。

显然，multipart/form-data已经足够好了，因为它到处都在使用。但如果你知道任何解决这个问题的替代方案，请在评论中告诉我！

七、总结

通过本文的介绍，我们可以看到 multipart 在文件上传中的重要性和优势。它不仅提高了文件上传的效率，还减少了内存消耗。尽管 multipart 的设计初衷是为了处理 HTML 表单中的文件上传，但它的应用范围远不止于此。无论是 Rust 还是其他编程语言，都可以利用 multipart 来实现高效、稳定的文件传输。

在实际应用中，我们可以通过选择合适的库和框架来简化 multipart 的处理过程。例如，在 Rust 中，我们可以使用 axum 或 reqwest 等库来轻松处理 multipart 请求。这些库提供了丰富的功能和良好的性能，可以帮助我们快速构建高效、可靠的文件上传功能。

此外，了解 multipart 的工作原理也有助于我们更好地优化和调整文件上传的策略。例如，我们可以通过调整边界分隔符的选择、优化 Content-Disposition 和 Content-Type 头部的设置等方式来提高文件上传的效率和稳定性。

最后，虽然 multipart 已经存在了很长时间，但它仍然是一个值得深入研究和探讨的话题。随着网络技术的不断发展和进步，我们可能会遇到更多新的挑战和需求。因此，持续学习和探索新的技术和方法是非常重要的。

希望本文能为你提供一些关于 multipart 的有价值的信息和启发。如果你有任何疑问或建议，请随时在评论区留言交流。