昔我往矣

uv 实战：Python 包构建与分发

Sun, 15 Mar 2026 23:33:21 +0800

从使用方式上区分，有两种Python项目，一种是应用程序，面向最终用户；一种是Python库项目，可以供其他项目使用，比如常用的requests、Flask、SQLAlchemy等库。本文探讨下uv如何支持Python的库开发与分发。

层层春山如黛。又是一个春天到了。

Python 的包管理机制随着Python的发展经历了几个阶段，逐渐发展成熟：

史前时代(1998 - 2000年)：开发者编写一个 setup.py 文件，用户下载源码后通过 python setup.py install 进行安装。用户需要手动下载和安装依赖。
变革时代：Setuptools 与 PyPI（2004年左右）：
- PyPI (Python Package Index) 诞生，成为了 Python 包的中央仓库。easy_install 可以自动从PyPI下载和安装依赖（但不支持卸载）。
- 引入setuptools工具和 Egg 格式，将代码和元数据（如版本、依赖、入口点）打包在一起。
经典时代，Pip 与 Wheel (2008 - 2014年)：
- pip 取代了 easy_install，引入了卸载功能和 requirements.txt 文件管理依赖，很长一段时间这都是最流行的方法。
- Wheel 格式 (.whl) 诞生（2012年）：它取代了 Egg 格式。Wheel 是预编译的二进制格式，安装速度极快，解决了“安装一个包得先装一堆编译器”的痛苦。
现代化（2018年至今）：PEP 517 & PEP 518 定义了打包的标准接口和构建时依赖问题，降低了对 setuptools 的强依赖。基于新的标准，Poetry、uv和pdm等开发管理工具提供了各自可用的构建后端，比如poetry-core、uv-build 和pdm-backend。

在 PEP 517 和 PEP 518 确立的现代标准下，Python 的打包流程被解耦为前端和后端。前端负责与用户交互，后端负责生成最终的产品（Wheel 或源码包）。在 pyproject.toml中可以声明项目使用的后端。项目的后端工具不一定要和前端匹配，比如uv也可以搭配 poetry-core 后端。

本文将基于uv创建一个Python包，并将其上传到自建的PyPI。演示完整的Python包开发、分发和使用的生命周期。

版本信息：

OS： Debian 13（Trixie）
Python：3.13
uv：0.10.7

universal-add 包开发

本文将开发 universal-add包，使其支持各类数据结构的加法操作。

创建项目

使用 uv 创建项目 universal-add，这个项目支持 int、float、string、set、dict等数据类型的加法。该项目仅仅作为演示，其中的逻辑并不重要，也不是真实存在的项目。

$ uv init --python ">=3.10"  universal-add   --package --description "an universal python add package"

指定了项目支持 python 3.10 及以上版本，使用包格式（src布局）初始化项目，并为项目设置一个描述。

以下是生成的 pyproject.toml 文件

[project]
name = "universal-add"
version = "0.1.0"
description = "an universal python add package"
readme = "README.md"
authors = [
    { name = "xnow", email = "xnow@xnow.me" }
]
requires-python = ">=3.10"
dependencies = []

[project.scripts]
uadd = "universal_add:main"  # 手动将 universal-add 修改为 uadd

[build-system]
requires = ["uv_build>=0.10.7,<0.11.0"]
build-backend = "uv_build"

pyproject.toml 文件的大部分内容我们都很熟悉了，有两项新增的配置：

[project.scripts]，指定uadd命令的入口函数为 universal_add包中的main()函数。把默认的 universal-add 修改为 uadd，安装后这个包的命令就变为了 uadd 。
[build-system] 就是uv指定的构建后端，这里使用了uv默认的后端 uv_build。

项目代码

进入项目目录，修改 src/universal_add/__init__.py 为如下内容：

import ast
import click
import sys
from typing import TypeVar, Union, TypeAlias

# Define type aliases for supported types
Addable: TypeAlias = Union[int, float, str, list, dict, set]
T = TypeVar("T", int, float, str, list, dict, set)


class IncompatibleTypeError(TypeError):
    """Raised when two types cannot be added or merged according to the defined logic."""

    pass


def add(a: T, b: T) -> T:
    """
    Universal addition core logic.
    """
    if not isinstance(b, type(a)) and not (
        isinstance(a, (int, float)) and isinstance(b, (int, float))
    ):
        raise IncompatibleTypeError(
            f"Cannot add {type(a).__name__} and {type(b).__name__}"
        )

    match a:
        case dict() | set():
            return a | b  # type: ignore
        case _:
            return a + b  # type: ignore


def smart_parse(value: str) -> any:
    """
    Convert CLI string input into Python objects safely.
    """
    try:
        return ast.literal_eval(value)
    except (ValueError, SyntaxError):
        # Fallback to raw string if it's not a valid Python literal
        return value


@click.command()
@click.argument("a")
@click.argument("b")
@click.version_option(version="0.1.0")
def main(a: str, b: str):
    """
    Universal Add CLI: A tool to add/merge numbers, strings, lists, and dicts.

    Example:
      uadd 1 2
      uadd "[1,2]" "[3,4]"
      uadd "{'key': 'val'}" "{'new': 1}"
    """
    try:
        # Parse inputs
        val_a = smart_parse(a)
        val_b = smart_parse(b)

        # Execute addition
        result = add(val_a, val_b)

        # Output result
        click.echo(result)

    except IncompatibleTypeError as e:
        click.secho(f"Error: {e}", fg="red", err=True)
        sys.exit(1)
    except Exception as e:
        click.secho(f"Unexpected Error: {e}", fg="yellow", err=True)
        sys.exit(1)


if __name__ == "__main__":
    main()

本项目的main()函数使用click接收和处理用户传入的参数，用户传入。安装click依赖：

$ uv add click
$ uv sync

项目名是 universal-add ，通过 uv tool install可以发布到全局uv 工具中，后续可以方便执行。

$ uv tool install . --editable   # --editable 模式，会同步项目代码的更改
$ uv tool list 
universal-add v0.1.0
- uadd

$ uv run uadd  100 200
300

$ uadd a b
ab

跟踪下底层逻辑：

$ which uadd
~/.local/bin/uadd

$ realpath ~/.local/bin/uadd
~/.local/share/uv/tools/universal-add/bin/uadd

$ cat ~/.local/share/uv/tools/universal-add/bin/uadd
#!/home/xnow/.local/share/uv/tools/universal-add/bin/python3
# -*- coding: utf-8 -*-
import sys
from universal_add import main
if __name__ == "__main__":
    if sys.argv[0].endswith("-script.pyw"):
        sys.argv[0] = sys.argv[0][:-11]
    elif sys.argv[0].endswith(".exe"):
        sys.argv[0] = sys.argv[0][:-4]
    sys.exit(main())

查看相应的 .pth 文件，指向了 universal-add 的开发目录。

$ cat ~/.local/share/uv/tools/universal-add/lib/python3.13/site-packages/universal_add.pth
/tmp/universal-add/src

.pth 文件提供了一种声明式的方法：只要在 site-packages 里放一个 <project name>.pth，里面写上项目的绝对路径，Python 就能像访问内置库一样访问你的项目。

好的，项目到这里就开发好了，接下来部署 PyPI 服务。

PyPI 部署和使用

Python官方中央仓库地址为 pypi.org，上传的地址为：https://upload.pypi.org/legacy/ 。 Python也提供了供练习使用的测试版本中央仓库，地址为 test.pypi.org，上传地址为 https://test.pypi.org/legacy/ 。

本文使用自建 PyPI 的方法测试Python包上传和下载使用。自建PyPI有多种方式，比较靠谱的是使用 Sonatype Nexus Repository 之类的成熟软件，可以host自己编写的包，也可以代理官方的PyPI。为了测试方便，我们使用 pypiserver 部署简易轻量PyPI，当前版本为 v2.4.1。

$ uv tool install pypiserver[passlib] --with bcrypt==4.0.1

这里的passlib是加密库，要给pypi设置密码就需要这个库。在bcrypt做密码加密的情况下，pypiserver需要安装对应的bcrypt库，使用 --with bcrypt==4.0.1 参数指定。

创建密码文件 password.txt，使用bcrypt 算法加密，用户名为 xnow，密码为 xnowXNOWxnow。如果bcrypt依赖不存在，先pip安装下。

$ python -c 'import bcrypt; user="xnow";passwd="xnowXNOWxnow"; print("%s:%s" % (user,bcrypt.hashpw(passwd.encode(), bcrypt.gensalt()).decode()))' > password.txt

启动 pypiserver ，监听到 8082 端口上：

$ mkdir pypi_data
$ pypi-server -P password.txt -p 8082 pypi_data/

启动免密 pypiserver的方法是 pypi-server -p 8082 pypi_data/ -a . -P .

上传 universal-add 项目

进入到 universal-add 项目目录，执行构建和发布操作

$ uv build
$ ls dist/
universal_add-0.1.0-py3-none-any.whl  universal_add-0.1.0.tar.gz

$ uv publish --publish-url=http://127.0.0.1:8082
Publishing 2 files to http://127.0.0.1:1888/
Enter username ('__token__' if using a token): xnow
Enter password: 
Uploading universal_add-0.1.0.tar.gz (1.4KiB)
Uploading universal_add-0.1.0-py3-none-any.whl (2.4KiB)

先使用 uv build 构建，会在项目的 dist/ 目录下创建 .whl和.tar.gz 文件。运行 uv publish ... 命令就是上传这两个文件到 PyPI上。

然后使用 uv publish 上传到PyPI。按提示输入用户名和密码即可。整个过程几乎不用关注构建过程的细节，对于新手开发者也十分的友好。

浏览器打开 http://127.0.0.1:8082/simple/，也可以看到上传的包。下载是不需要认证的。

新项目中安装 universal-add

打开新的命令行窗口，创建一个测试用的新项目 testproj

$ uv init testproj
$ cd testproj
$ uv add universal-add --index http://127.0.0.1:8082/simple

$ uv tree
Resolved 4 packages in 1ms
testproj v0.1.0
└── universal-add v0.1.0
    └── click v8.3.1

$ uv run python -c 'from universal_add import add; print(add("hello ", "42"))'
hello 42

安装 universal-add 依赖的时候，用--index指定本地搭建的 pypiserver 服务。通过 uv tree 和 uv run ... 验证确认功能正常可用。

总结

本文基于 uv 完整演示了 Python 包从创建、开发、构建、发布到私有 PyPI 的流程，同时说明了 PEP 517/518 下前端与后端解耦的构建体系。借助 uv 的工具链和 pypiserver 的轻量部署，可以在本地快速完成包开发与分发的闭环验证。

在新标准中，Python 包的分发已经变得十分简单和新手友好，降低了构建门槛。对 Python 生态发展具有里程碑的意义。

极快的python项目管理工具：uv使用指南

Sun, 08 Mar 2026 22:17:41 +0800

上一篇文章介绍了新一代的 Python 项目管理工具 Poetry，解决了 Python 项目难以管理的问题。本文将介绍另一款 Python 项目管理工具 uv，uv 是由 Astral 团队打造的下一代 Python 项目与包管理工具，目标是替代 pip、pip-tools 和 virtualenv ，为 Python 生态带来更快的依赖解析和安装体验。

uv 官网的介绍是 用 Rust 编写的极快速的 Python 打包和项目管理工具。uv 之所以快，不仅因为用 Rust 重构，还在于其全局缓存与依赖解析算法优化。uv 仍在快速迭代中，强烈推荐 Python 开发者使用。

版本信息

OS: Debian 13 (Trixie)
Python: 3.13
uv: 0.10.7

安装 uv

建议用 pipx 安装 uv

$ pipx install uv -i https://mirrors.aliyun.com/pypi/simple
$ uv --version
uv 0.10.7

uv help 可以列出 uv 支持的所有命令。

$ uv help
...
  run                        Run a command or script
  init                       Create a new project
  add                        Add dependencies to the project
  remove                     Remove dependencies from the project
  version                    Read or update the project's version
  sync                       Update the project's environment
  lock                       Update the project's lockfile
...

项目管理

uv 既可以用于新项目，也可以快速适配到已有的 Python 项目中。其用法十分简单直观。

创建项目

无论是创建新项目，还是将已有项目交给 uv 管理，都使用 uv init 命令。区别在于：创建新项目需要传递项目名（即目录名）；初始化已有项目则不需要任何参数。

下面创建一个新项目，看看 uv 做了哪些事。

$ uv init newproj
Initialized project `newproj` at `/tmp/newproj`

$ ls -a newproj
.  ..  .git  .gitignore  main.py  pyproject.toml  .python-version  README.md

$ cd newproj
$ uv run main.py
Using CPython 3.13.5 interpreter at: /usr/bin/python3.13  # 使用系统中的Python版本
Creating virtual environment at: .venv  # 创建虚拟环境
Hello from newproj!                     # 虚拟环境中运行脚本

$ uv run which python   # 虚拟环境中的Python
/tmp/newproj/.venv/bin/python   # 实际是 /usr/bin/python3.13 的软链接

使用 uv init 创建名为 newproj 的新项目。可以用 --python 3.xx 指定虚拟环境 Python 版本；不指定时使用系统全局版本。
查看新项目目录内容：
- .git 和 .gitignore 是基础的 Git 目录和文件；.gitignore 内含常见忽略项，例如 __pycache__/、.venv。
- main.py 是示例脚本，包含基础 main 函数。
- pyproject.toml 是 PEP 定义的标准项目配置文件，uv 大多数操作都围绕它展开。
- .python-version 记录项目使用的 Python 版本，例如 3.13。
- README.md 是项目说明文档，默认为空。
使用 uv run <command> 会在当前 uv 环境中运行命令，并自动创建 .venv 目录和 uv.lock 文件。

pyproject.toml 内容很精简，仅包含基本项目信息，建议按实际需要调整。

[project]
name = "newproj"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

uv init 可通过参数决定项目类型，不同类型的目录结构略有区别：

--bare：仅创建 pyproject.toml，不创建其他文件和目录。
--package：创建 src 布局目录（如 src/包名）。pyproject.toml 额外包含 [project.scripts] 和 [build-system]，用于运行和打包。
--lib：与 --package 类似，但不包含 [project.scripts]。
--app：应用类型项目，默认结构。采用扁平布局，无 src 目录，pyproject.toml 中也没有运行或打包配置段。
--script：不创建 pyproject.toml，仅创建一个脚本文件，文件开头包含注释形式的 pyproject.toml 片段，用于管理脚本依赖。

这些选项仅决定初始化时的目录结构，项目用途与使用方式仍可按需调整。

PyPI 源

国内从官方 PyPI 源安装依赖通常较慢，可设定国内镜像作为默认源以提升速度。在 pyproject.toml 中添加：

[[tool.uv.index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple"
default = true

安装和卸载

uv 使用 add 和 remove 管理依赖的安装与卸载。

进入 newproj 目录，安装依赖：

$ uv add aiohttp httpx

$ grep -A3 ^dependencies pyproject.toml 
dependencies = [
    "aiohttp>=3.13.3",
    "httpx>=0.28.1",
]

安装的依赖会记录在 pyproject.toml 中。版本区间写法如 >=3.13,<3.15，该写法可用于 Python 版本约束与依赖版本约束。

卸载依赖：

$ uv remove aiohttp
$ grep -A3 ^dependencies pyproject.toml 
dependencies = [
    "httpx>=0.28.1",
]

卸载后，只剩一项依赖。

在添加或删除依赖时，uv 会完成 3件事：

将依赖下载到 uv 的用户级全局缓存中，并从缓存安装到虚拟环境。
将依赖写入 pyproject.toml。
将依赖解析结果写入 uv.lock。uv.lock 是项目依赖快照，包含直接与间接依赖、来源、版本与哈希等信息。

uv 还提供几种常见的依赖安装方式：

从 requirements.txt 文件中安装依赖，并写入 pyproject.toml：

$ uv add -r requirements.txt

也可以将 uv.lock 中的依赖导出为 requirements.txt 格式：

$ uv export --format requirements.txt

升级特定依赖：

$ uv add --upgrade requests

将项目上传到 Git 仓库时，不应提交 .venv 目录，一般只需要提交 pyproject.toml 和 uv.lock。运行时基于 uv.lock，uv sync 能快速恢复项目依赖，精确到每个依赖的具体版本。

$ uv sync

查看项目的依赖关系树形图

$ uv tree
newproj v0.1.0
└── httpx v0.28.1
    ├── anyio v4.12.1
    │   └── idna v3.11
    ├── certifi v2026.2.25
    ├── httpcore v1.0.9
    │   ├── certifi v2026.2.25
    │   └── h11 v0.16.0
    └── idna v3.11

依赖组

添加两个依赖组，分别为 dev 和 test，用于管理开发与测试阶段依赖。

$ uv add ruff --group dev
$ uv add pytest --group test

uv add --group dev 等价于 uv add --dev <PACKAGES>。

检查 pyproject.toml 文件内容，依赖组定义在 dependency-groups 中：

$ grep -A6 dependency-groups  pyproject.toml 
[dependency-groups]
dev = [
    "ruff>=0.15.5",
]
test = [
    "pytest>=9.0.2",
]

uv sync 提供以下选项以决定安装哪些依赖组：

--no-dev ：禁用dev依赖组。
--only-dev：仅包含dev依赖组
--group <GROUP> ：指定特定依赖组，
--no-group <NO_GROUP>：排除指定依赖组
--no-default-groups ：排除默认的依赖组
--only-group <ONLY_GROUP>：仅包含特定的依赖组
--all-groups ：安装所有依赖组。

除了依赖组 dependency-groups 之外，uv 还支持可选依赖（optional dependencies）。两者用法相近，但职责不同：

dependency-groups 用 --group 之类的参数控制；optional dependencies 用 --extra <EXTRA> 控制。
dependency-groups 记录在 pyproject.toml 的 [dependency-groups] 表中；optional dependencies 记录在 [project.optional-dependencies] 中。
dependency-groups 一般用于开发、测试、CI 等阶段依赖；optional dependencies 更适合库项目的可选功能（如不同数据库后端）。

uv 各子命令对 dependency-groups 与 optional dependencies 的操作支持相对一致，可按项目需求选择。

uv.lock

uv.lock 记录当前解析出的依赖集合，是项目依赖的快照。使用 uv sync 可恢复出一致的项目环境，对应用类型的 Python 项目尤其有用。

如果 uv.lock 丢失，可用 uv lock 重新生成 uv.lock。

$ uv lock

可以手动编辑 pyproject.toml，但千万不要手动编辑 uv.lock 文件

link-mode 与缓存

uv 可通过环境变量控制行为，其中 UV_LINK_MODE 用于决定从全局缓存安装软件包的方式，可选值有 clone、copy、hardlink、symlink。从缓存获取依赖，是 uv 速度提升的重要原因之一。

clone：将源目录中的包克隆（写入时复制）到目标目录，默认选项。
copy：将包从源位置复制到目标位置。
hardlink：将源包硬链接到目标位置。
symlink：将源目录中的包以符号链接方式指向目标目录。不建议使用此模式，清理缓存可能导致依赖失效。

除了环境变量，uv 也支持使用 --link-mode 指定模式，该行为也可写入 pyproject.toml：

[tool.uv]
link-mode = "copy"

uv cache dir 查看缓存目录位置：

$ uv cache dir
~/.cache/uv

uv cache size 查看缓存大小：

$ uv cache size --human
26.7MiB

uv cache clean 清理缓存。可指定删除特定包，默认删除全部缓存。

$ uv cache clean        # 清理系统的全部缓存
$ uv cache size --human # 查看清理后，缓存大小为0
0

uv cache prune 命令比uv cache clean 智能一些，只会清理不再使用的缓存包。

除 --link-mode 外，uv 还支持 --offline 模式禁用网络，仅使用本地缓存安装依赖；若依赖缺失则直接报错。该行为也可在 pyproject.toml 中配置：

[tool.uv]
offline = true

虚拟环境

uv 不仅可以使用系统中已有的 Python，还能从 uv 的 Github 仓库中在线下载和安装指定版本的 Python。

Python 版本管理

uv 支持在线下载并安装指定的 Python 版本。查看 uv 安装 Python 的路径：

$ uv python dir
~/.local/share/uv/python

查看当前已安装和可安装的版本列表：

$ uv python list 
cpython-3.15.0a6-linux-x86_64-gnu                 <download available>
cpython-3.15.0a6+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.14.3-linux-x86_64-gnu                   <download available>
cpython-3.14.3+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.13.12-linux-x86_64-gnu                  <download available>
cpython-3.13.12+freethreaded-linux-x86_64-gnu     <download available>
cpython-3.13.5-linux-x86_64-gnu                   /usr/bin/python3.13   # 系统的全局 Python 版本
...

在线安装 Python

$ uv python install 3.14

在项目中临时使用 Python 3.14 运行：

$ uv run --python 3.14 python -c 'import sys; print(sys.version)'                                                                                  
3.14.3 (main, Feb 12 2026, 00:42:54) [Clang 21.1.4 ]

修改当前项目运行的 Python 版本：

$ uv python pin 3.14
Pinned `.python-version` to `3.14`

$ uv run python --version
Python 3.14.3

使用 uv python pin 3.14 会更新项目目录下的 .python-version 为 3.14。由于仍满足 pyproject.toml 中 requires-python = ">=3.13" 的要求，所以无需修改 pyproject.toml。若不满足约束，会报兼容性错误，需要手动修改 pyproject.toml 的限制条件。

uv pip

使用 uv pip ... 在虚拟环境中安装包：

$ uv pip install ipython
$ uv pip list | grep ipython
ipython                 9.11.0

注意：使用 uv pip install 安装的软件包不会记录到 pyproject.toml 和 uv.lock 中，执行 uv sync 时会被移除。

uv 的其他用法

除了上面的基础项目管理和虚拟环境等基础功能外，uv 还有一些其他很有用的玩法。

uv format

uv format 命令可以用于代码的格式化，底层使用 ruff ，支持如下两个参数：

--check：检查代码是否已经符合格式要求，不执行格式化
--diff：以 diff 的形式显示 format 将会对代码做哪些变动。

不加参数的情况下，uv format 会默认自动对代码做格式化。也可以仅对指定 Python 文件做 format 格式化。

uv 会自动寻找项目目录下和全局的 ruff 配置文件（比如：~/.config/ruff/ruff.toml），以便确定 ruff 的 format 规则。

uvx 和 uv tool

uv tool 是 uv 提供的全局工具箱管理，用于安装或在隔离环境中运行 Python CLI 工具，功能类似 pipx。子命令包括：

install/uninstall/list/upgrade：安装/卸载/列表/升级工具
run：运行工具，等价于 uvx。工具不存在时会自动安装到缓存并运行。
dir：查看工具安装路径。

uv tool run（即 uvx）的目标是“无需安装、即时运行”。它会创建临时环境用于运行，环境会被缓存以便复用，非常适合偶尔使用的工具。 uv tool install 则将工具安装为全局可用命令。

查看工具安装的目录

$ uv tool dir
~/.local/share/uv/tools

使用 uvx 和 uv tool run 临时安装并运行 httpx 工具：

$ uv tool run httpx[cli] http://xnow.me   # uv tool run 临时安装和测试
$ uvx  httpx[cli] http://xnow.me          # uvx 临时安装和测试

$ uv tool list                           # 工具列表为空

安装 httpx 工具并检查安装路径：

$ uv tool install httpx[cli] --force  # 安装 httpx 工具

$ uv tool list      # 检查工具列表，其中包含了 httpx
httpx v0.28.1
- httpx

$ which httpx   # 已经有了全局的 httpx 命令
~/.local/bin/httpx

$ ls -lh ~/.local/bin/httpx     # 检查全局 httpx 命令，来自于 uv tool 目录下
lrwxrwxrwx 1 1000 1000 48 Mar  8 16:40 ~/.local/bin/httpx -> ~/.local/share/uv/tools/httpx/bin/httpx

因此，如果要经常使用的命令，建议用 uv tool install 做安装和使用。

为特定依赖使用特定源

PyTorch 官方源有些奇怪，默认的 PyPI 中只有 GPU 版本的依赖库，如果要安装 CPU 版本的PyPI，则需要指定专门支持 CPU 的 PyPI 源。因此，可以在 ptproject.toml 中添加专门的源，并指定 torch 包使用这个源安装。配置如下：

[tool.uv.sources]
torch = { index = "pytorch-cpu" }

[[tool.uv.index]]
name = "pytorch-cpu"
explicit = true
url = "https://download.pytorch.org/whl/cpu"

某些场景下建议显式使用 PyTorch 官方 index，效果等价于 -i https://download.pytorch.org/whl/cpu。

explicit = true 表示默认不使用该源，只有明确指定时才会使用。

run 的临时依赖

如果不想将临时依赖写入 dev 依赖组，可用 --with 临时指定，例如为 Flask 的 shell 使用 IPython：

$ FLASK_APP=hello.py uv run --with flask-shell-ipython flask shell

uv 脚本

uv 的脚本管理功能在运维脚本场景中非常实用。使用 uv 初始化脚本时，脚本自动内置依赖管理，不创建 pyproject.toml。

$ uv init --script test.py     # 初始化脚本
Initialized script at `test.py`

$ cat test.py               # 查看脚本内容
# /// script
# requires-python = ">=3.13"
# dependencies = []
# ///

def main() -> None:
    print("Hello from test.py!")


if __name__ == "__main__":
    main()

test.py 如果不存在， uv 会自动创建，内容如上。如果 test.py 脚本已经存在， uv 会在脚本已有内容的基础上，在文件开头增加依赖管理相关的注释行。

可以手动或使用 uv 命令为该文件管理依赖：

$ uv add requests --script test.py

$ grep dependencies test.py  -A 2
# dependencies = [
#     "requests",
# ]

$ uv run test.py
Installed 5 packages in 23ms
Hello from test.py!

uv add requests --script test.py 会将依赖更新到脚本文件开头。
uv run test.py 会解析脚本中定义的依赖并创建虚拟环境。脚本虚拟环境位于 ~/.cache/uv/environments-v2/，不同脚本之间彼此隔离。

如果觉得频繁使用 uv run 不便，可在脚本第一行添加 shebang：#!/usr/bin/env -S uv run。授予可执行权限后，./a.py 等价于 uv run a.py。

使用 uv lock --script test.py 会创建或更新 test.py.lock，记录脚本依赖及版本。

探索 uv 的其他用法

uv 项目仍在快速发展中，有些使用方法还在预览阶段。如果遇到问题，建议到 uv 的官方文档中寻求解答。uv 的配置项和环境变量尤其有用，建议看看。

uv 配置项：https://docs.astral.sh/uv/reference/settings/ uv 环境变量：https://docs.astral.sh/uv/reference/environment/

uv 的优势在于“快”和“可重复”。无论是日常开发还是脚本工具化，uv init/add/sync 覆盖了大多数场景，配合 uv.lock 能稳定复现依赖环境。

总结

本文从日常开发需求入手，介绍了 uv 在 Python 项目开发各个阶段的用法。不论是初级还是资深Python研发工程师，都建议尝试uv，随着 uv 的发展，应该会有更多惊艳功能出现。

Python项目管理工具：Poetry 使用指南

Sun, 01 Mar 2026 22:19:29 +0800

在项目开发中，良好的代码管理工具至关重要。对于 Python 开发而言，核心诉求是管理项目依赖、虚拟环境、项目元信息等。近年来，一系列 PEP（Python 增强提案）规范了使用 pyproject.toml 文件进行项目依赖、构建和元信息管理。伴随着标准落地，许多新工具渐次发布，首当其冲的就是 Poetry。Poetry 是用于 Python 的依赖管理和打包工具，设计目标是简化和提升 Python 包的创建、管理与发布过程。在 Poetry 官网中对其的介绍是：Poetry 是让 Python 打包和依赖管理更加轻松的工具。

本文将通过实际操作的方式，一步步了解 Poetry 的功能与常见工作流。本文基于以下版本进行演示：

OS：Debian 13（Trixie）
Python：3.13
poetry：2.3.2

Poetry 还在快速更新迭代中，有些配置和用法可能会因版本差异而不同，请注意区分。

安装和使用

安装 Poetry 的方法见官方文档： https://python-poetry.org/docs。不同平台有各自的安装方法，建议使用 pipx 安装。

$ pipx install poetry
$ poetry --version
Poetry (version 2.3.2)

Poetry 版本升级方法：

$ pipx upgrade poetry

Poetry 常用命令速览：

$ poetry new
$ poetry init
$ poetry add
$ poetry remove
$ poetry install
$ poetry sync
$ poetry run

项目管理

以下命令可以用于了解 Poetry 的用法和版本信息等。

$ poetry list
$ poetry about

子命令介绍： + list 查看所有 Poetry 支持的子命令。 + about 查看 Poetry 的版本等信息。

Poetry 有一个全局性的 --verbose 选项，或者 -v/-vv/-vvv，可以用来观察 Poetry 的 debug 信息和具体的运行过程。

Poetry 的全局配置

查看 Poetry 的默认配置：

$ poetry config --list
cache-dir = "~/.cache/pypoetry"       # 缓存目录
data-dir = "~/.local/share/pypoetry"
installer.max-workers = null
virtualenvs.path = "{cache-dir}/virtualenvs"   # 项目虚拟环境目录
...

设置 Poetry 的配置项。修改 Poetry 的全局配置会影响 Poetry 的行为，谨慎修改。

$ poetry config virtualenvs.in-project true
$ poetry config repositories.aliyun https://mirrors.aliyun.com/pypi/simple/

修改 virtualenvs.in-project 配置项为 true。默认情况下，Poetry 会在 virtualenvs.path 配置规定的目录下创建项目的虚拟环境，修改该项为 true 后，Poetry 会在项目目录下创建虚拟环境，目录为 .venv。
配置一个名为 aliyun 的 PyPI 源，修改为国内源以提升依赖安装速度。

Poetry 的配置保存在 ~/.config/pypoetry/config.toml 文件中。

$ cat ~/.config/pypoetry/config.toml
[virtualenvs]
in-project = true

[repositories.aliyun]
url = "https://mirrors.aliyun.com/pypi/simple/"

以上是比较常见的 Poetry 全局指令。接下来是和项目管理相关的内容。

创建新项目

使用 Poetry 的 new 子指令创建一个全新的项目。

$ poetry new myproj
Created package myproj in myproj
$ tree myproj
myproj
├── pyproject.toml
├── README.md
├── src
│   └── myproj
│       └── __init__.py
└── tests
    └── __init__.py

new 子命令创建新的 Python 项目。新项目目录包含基础的项目结构，除 pyproject.toml 外还会生成 README.md、tests 等基础文件，内容多为占位信息。

Python 项目有两种常见结构：一种是把包放在项目的顶级目录下，一般称为 flat 布局，许多 Web 项目都是这么做的；另一种是把包放到项目的 src 目录下，称为 src 布局，许多库项目采取了这种方式。Poetry 默认采用 src 布局，如果想使用 flat 布局，可以传入 --flat 参数。

$ poetry new myproj2 --name app --flat
Created package app in myproj2

$ tree myproj2
myproj2
├── app
│   └── __init__.py
├── pyproject.toml
├── README.md
└── tests
    └── __init__.py

--name 参数用于指定创建项目的包名，如果不指定，包名和项目名一样。
--flat 指定创建 flat 布局项目，包名 app 就在项目顶级目录下，没有 src 目录了。生成的 pyproject.toml 文件也有细微区别。

初始化已有项目

如果现有项目要切换到 Poetry 进行管理，可以使用 init 指令，会在现有项目中创建 pyproject.toml 文件。

$ mkdir myproj3
$ cd myproj3
$ poetry init --no-interaction   # 不使用交互式输入项目信息

$ ls
pyproject.toml   # 仅仅创建了 pyproject.toml 文件

Poetry 初始化项目的工作十分简单，只新增了一个 pyproject.toml 文件。如果 init 指令不使用 --no-interaction 参数，Poetry 会出现交互式配置提示，需要一步步填入项目元信息。

check 子命令用于检查 pyproject.toml 文件的格式是否正确。

$ poetry check 
All set!

项目配置

Poetry 通过 pyproject.toml 文件实现大部分管理功能，部分 Poetry 子命令（比如 add、remove 等）会修改这个文件，这个文件也可以手动修改。

pyproject.toml 并不是 Poetry 的发明，PEP 518 定义了该文件作为构建配置入口，PEP 621 定义了 [project] 元信息规范。其他符合 PEP 规范的工具也可以使用这个文件。

以下是 myproj2 项目的 pyproject.toml 文件

$ cd myproj2

$ cat pyproject.toml 
[project]
name = "app"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

在 TOML 格式中，方括号代表 table，类似一个子 JSON，其中的等号定义内容相当于 JSON 中的键值对。

[project] 定义了项目的元信息，例如 name、version、description、authors 等。
requires-python 指定本项目依赖的 Python 版本。
dependencies 用于指定本项目的依赖。
[build-system] 中指定了库项目构建相关的依赖和构建后端。使用 Poetry 打包/发布时必须保留该部分；即便是应用项目，保留默认配置也更稳妥。

PyPI 源管理

在 Poetry 管理的项目中，可以使用 source 子命令管理 PyPI 源，source 子命令下有 add、show、remove 等子命令用于对 PyPI 源进行管理。

$ poetry source add aliyun https://mirrors.aliyun.com/pypi/simple
$ poetry source add douban https://pypi.doubanio.com/simple

$ poetry source show
 name      : aliyun                                 
 url       : https://mirrors.aliyun.com/pypi/simple 
 priority  : primary                              

 name      : douban                           
 url       : https://pypi.doubanio.com/simple 
 priority  : primary

aliyun 和 douban 两个源的优先级都是 primary，当存在多个 primary 源时，Poetry 会按它们在 pyproject.toml 中的顺序进行查找；未显式指定 --source 的依赖通常会优先走第一个 primary 源。

如果需要从特定的 source 安装依赖，可以用 --source 指定源站。

$ poetry add flask --source douban

在运行上面的命令之后，目录下会产生 poetry.lock 文件，它非常重要，记录了当前项目的依赖关系和依赖版本等信息，相当于一个快照，poetry sync 等命令会读取 poetry.lock 还原出完全一致的依赖环境。

再次查看 pyproject.toml 文件，重点看看其中的依赖部分：

[project]
...
requires-python = ">=3.13"
dependencies = [
    "flask (>=3.1.3,<4.0.0)"
]

[[tool.poetry.source]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple"
priority = "primary"


[[tool.poetry.source]]
name = "douban"
url = "https://pypi.doubanio.com/simple"
priority = "primary"


[tool.poetry.dependencies]
flask = {source = "douban"}

project.dependencies 中指明了项目依赖的 flask 版本。
[tool.poetry.dependencies] 中指明了 Flask 依赖来自的源。这在某些场景很有用，比如英伟达的 CUDA 源分为 CPU 版本和 GPU 版本，CPU 就要使用特定的源才能安装。

非 package 项目

Poetry 项目分两种模式：

默认是 package 模式：意味项目需要被打包和发布，这种模式下 pyproject.toml 中的 version 是强制必填字段，运行 poetry install 会安装当前项目。一般采用 src 项目布局。
non-package 模式：意味这是应用类型的项目。一般使用 flat 项目布局。

在 [tool.poetry] 中添加如下配置，指定为 non-package 模式。

package-mode = false

一般来说，用什么模式的区别不大，项目的布局更重要一些。不管是不是 package 模式，都建议设置 version 字段。

poetry run

使用 poetry run 会在当前的 Poetry 环境中运行命令。如果虚拟环境还不存在，运行这个命令会创建虚拟环境。

$ poetry run which python
/tmp/myproj2/.venv/bin/python

$ poetry run flask --version
Python 3.13.5
Flask 3.1.3
Werkzeug 3.1.6

依赖管理

管理 Python 版本

较新版本的 Poetry 支持安装特定版本的 Python 了。先看看当前虚拟环境中的 Python 版本。

$ poetry env info
Virtualenv
Python:         3.13.5
Implementation: CPython
Path:           /tmp/myproj2/.venv
Executable:     /tmp/myproj2/.venv/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.13.5
Path:       /usr
Executable: /usr/bin/python3.13

和系统 Python 版本一致，是 3.13。Poetry 的 python 子命令有 install、list、remove 3 个子命令管理项目的 Python 版本。

$ poetry python list --all
 Version  Implementation Manager Path
 3.14.3t  CPython        Poetry  Available for download
 3.14.3   CPython        Poetry  Available for download
...

上面的命令会列出所有可用的 Python 版本，Available for download 表示可以下载安装。如果不使用 --all 参数，只会列出本地已有的 Python 版本。

安装 Python 3.11 试试看:

$ poetry python install 3.11
Downloading and installing 3.11 (cpython) ... Done
Testing 3.11 (cpython) ... Done

$ poetry python list
Version Implementation Manager Path
3.13.5  CPython        System  /usr/bin/python3.13
3.13.5  CPython        System  /usr/bin/python3
3.13.5  CPython        System  /bin/python3.13
3.13.5  CPython        System  /bin/python3
3.11.14 CPython        Poetry  ~/.local/share/pypoetry/python/cpython@3.11.14/bin/python3.11
3.11.14 CPython        Poetry  ~/.local/share/pypoetry/python/cpython@3.11.14/bin/python3
3.11.14 CPython        Poetry  ~/.local/share/pypoetry/python/cpython@3.11.14/bin/python

安装过程就是到 GitHub 的 python-build-standalone 仓库下载对应版本的 Python 包安装。

可以看到 Poetry 把 Python 3.11 安装到 ~/.local/share/pypoetry/python/ 目录下了。

然后修改 pyproject.toml 文件，编辑 requires-python 一行，指定使用 Python 3.11 版本：

requires-python = ">=3.11,<3.12"

删除旧的 3.13 版本虚拟环境，然后切换为 3.11 并重建虚拟环境。

$ poetry env remove
Deleted virtualenv: /tmp/myproj2/.venv

$ poetry update
Creating virtualenv app in /tmp/myproj2/.venv
Writing lock file

$ poetry env info

Virtualenv
Python:         3.11.14
Implementation: CPython
Path:           /tmp/myproj2/.venv
Executable:     /tmp/myproj2/.venv/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.11.14
Path:       ~/.local/share/pypoetry/python/cpython@3.11.14
Executable: ~/.local/share/pypoetry/python/cpython@3.11.14/bin/python3.11

$ poetry run python --version
Python 3.11.14

先删除旧的虚拟环境，然后运行poetry update 会新建 3.11 版本的虚拟环境。新的 .venv 环境里的 Python 版本是 3.11，也显示了 3.11 环境基于 Poetry 安装在用户目录下的 Python。

管理依赖

从 PyPI 里查找包，可以看到把 aliyun 这个 PyPI 源中匹配 aiohttp 的包都列出来了。

$ poetry search aiohttp
 Package                                                    Version     Source Description 
 aiohttp                                             0.1          aliyun             
 aiohttp                                             0.2          aliyun             
 aiohttp                                             0.3          aliyun             
 aiohttp                                             0.4          aliyun    
 ...

add 和 remove 子命令分别用来安装和卸载依赖，都会同步修改 pyproject.toml 文件。

$ poetry add "aiohttp>2,<3" httpx

$ poetry show aiohttp
 name         : aiohttp                                      
 version      : 2.3.10                                       
 description  : Async http client/server framework (asyncio) 
...

使用 > 或者 < 限制版本时要使用引号，因为它们在 shell 中有重定向的含义。如果指定的版本和之前不一样，Poetry 会重新安装成新指定的版本，并更新 pyproject.toml 文件。

上面指定了 aiohttp 的版本范围，实际安装的是符合条件的最高版本。pyproject.toml 文件中也做了相应的变更。

$ grep -E  ^dependencies -A 4  pyproject.toml
dependencies = [
    "flask (>=3.1.3,<4.0.0)",
    "aiohttp (>2,<3)",
    "httpx (>=0.28.1,<0.29.0)"
]

上传项目到 Git 时，建议上传 pyproject.toml 和 poetry.lock 两个文件，不要上传 .venv。

注意：如果开发的是库（library），而不是应用（application），则往往不需要上传 poetry.lock 到代码版本管理仓库，因为库需要保持多个依赖版本的兼容性，如果写死版本，很可能会产生依赖冲突。

当把这个项目迁移到新环境或者目录时，可以使用 poetry sync 解析并安装所有依赖，这个命令提供了 --dry-run 选项，可以只输出操作，不实际运行。

$ poetry sync

poetry add 和 pip install 安装依赖时都会分析包的依赖，并解决依赖。在执行 poetry remove 时，Poetry 会删除依赖的库，而 pip uninstall 则不会，pip 只会删除指定库。

依赖组

有些依赖仅仅在开发阶段使用，比如 lint 工具；有些是在软件测试中用到的，比如 pytest。生产环境运行时应该保持最精简的状态和最小体积，不需要安装这些开发和测试阶段的依赖。为了区分依赖，可以新增 dev 和 test 两个可选（optional）依赖组，依赖组的名字可以随意指定，但建议使用有意义的词汇。

$ poetry add --group dev ruff autopep8
$ poetry add --group test pytest

$ grep -A7 "dependency-groups" pyproject.toml 
[dependency-groups]
dev = [
    "ruff (>=0.15.4,<0.16.0)",
    "autopep8 (>=2.3.2,<3.0.0)"
]
test = [
    "pytest (>=9.0.2,<10.0.0)"
]

从结果可以看到，pyproject.toml 中多了 [dependency-groups] 子表，内容是指定安装的依赖。在 [project] 中 dependencies 里定义的依赖是 main 组。

默认情况下，install 命令会安装所有依赖组。使用 --with 安装可选组，使用 --without 排除可选组，使用 --only 只安装某些组。

$ poetry install --only=dev,main
$ poetry install --without=test

在目前的 pyproject.toml 配置下（只有 main、dev、test 这三个组），上面两个命令的效果等价。

注意：使用 --only 时，Poetry 会自动忽略 --with 和 --without 选项。

使用 show 子命令可以查看依赖的安装情况，默认会把间接依赖也列出来，使用 --tree 以树形方式展示依赖关系，使用 --top-level 选项只列出 pyproject.toml 文件中指定的顶级依赖。

poetry.lock 文件

上面说过，poetry.lock 文件详细记录了当前项目所有依赖包的精确版本信息，包括直接依赖和间接依赖，相当于当前项目依赖情况的一个快照。不要手动修改 poetry.lock 文件。

如果手动修改了 pyproject.toml 文件的依赖项，可能会导致 poetry.lock 中的依赖不一致。运行 poetry install 时会报错：

$ poetry install
Installing dependencies from lock file

pyproject.toml changed significantly since poetry.lock was last generated. Run `poetry lock` to fix the lock file.

$ poetry lock
Resolving dependencies... (3.0s)

Writing lock file

poetry install 时的输出提示 pyproject.toml 和 poetry.lock 文件内容不同步，需要运行 poetry lock 来更新 poetry.lock 文件。

注意：poetry lock 这个命令只会更新 poetry.lock 文件的依赖条目，并不会安装依赖。而且这个过程会遍历所有直接依赖的依赖项，以便解决潜在的依赖版本冲突问题。

依赖锁定主要解决如下两个问题： + 解析：找到满足所有依赖限制下的解决方案，避免出现间接依赖的版本冲突。 + 锁定：通过 poetry.lock 文件为当前所有依赖项创建快照。

使用 poetry lock --regenerate 会忽略已有的 poetry.lock 文件，重新创建一个 poetry.lock 文件覆盖旧的。

执行 poetry install 会安装 poetry.lock 文件中的所有依赖，且只安装环境中缺失的那部分。

如果环境中存在 poetry.lock 和 pyproject.toml 中未记录的依赖怎么办？比如，使用 pip 往虚拟环境中安装的依赖。使用 poetry sync 不止会依赖检查、安装和同步，也会清理环境中未被记录的依赖。

$ poetry run pip install requests

$ poetry sync
Installing dependencies from lock file

Package operations: 0 installs, 0 updates, 3 removals

  - Removing charset-normalizer (3.4.4)
  - Removing requests (2.32.5)
  - Removing urllib3 (2.6.3)

Installing the current project: app (0.1.0)

使用 sync 子命令，Poetry 移除了虚拟环境中没有被 poetry.lock 文件记录的依赖，使得虚拟环境和 poetry.lock 的依赖保持一致。

poetry install 和 poetry sync 命令的功能十分相似，都可以安装指定的依赖项，但有两点不一样：

poetry install 不会清理环境中 Poetry 未记录的依赖，而 poetry sync 会清理。sync 比 install 更严格。
如果是 package 项目，poetry install 会把当前的项目作为依赖安装。

依赖升级

Poetry 的 show 子指令可以查看项目依赖的情况：

$ poetry show aiohttp
$ poetry show --latest

查看 aiohttp 包的版本和依赖关系
--latest 查看依赖可用的最新版本

如果依赖有满足条件的新版本，可以使用 update 子命令进行更新。

$ poetry update aiohttp
$ poetry update

以上示例分别用于更新指定的依赖和更新所有依赖。update 也支持 --dry-run 选项，由于版本升级总是伴随冲突风险，建议升级前查看具体升级了哪些依赖。

如果要突破 pyproject.toml 文件中的版本限制进行升级，比如 aiohttp 2.3.10 升级到 aiohttp 3.3.0，或者直接升级到最新版本，需要通过如下的 add 指令操作，这个命令也会同步修改 pyproject.toml 中的依赖版本限制。

$ poetry add "aiohttp<3.10"
$ grep aiohttp pyproject.toml 
    "aiohttp (<3.10)",

$ poetry show aiohttp 
 name         : aiohttp                                      
 version      : 3.9.5
 ...

升级依赖版本和新增依赖一样，都是 add 子命令；通过新的版本约束触发重新解析并升级到符合条件的版本。

虚拟环境

如果 Poetry 的全局配置项 virtualenvs.in-project=false，Poetry 项目的虚拟环境会放在用户目录下的 .cache/pypoetry/virtualenvs，可以为一个项目支持多个不同的 Python 环境，以便切换多个版本进行测试。当 virtualenvs.in-project=true，项目的虚拟环境就是项目目录下的 .venv 目录，就无法再支持多版本了。

Poetry 在运行时，会通过检查 pyproject.toml 文件检测当前是否在 Poetry 环境中，是否已经有虚拟环境。如果 Poetry 项目中还没有虚拟环境，Poetry 会自动创建虚拟环境后执行命令。下面是临时把 virtualenvs.in-project 改为 false 之后，测试多个版本的 Python 环境。

$ poetry config virtualenvs.in-project false   # 设置虚拟环境为用户目录下，而非项目目录下

$ sed -i 's/^requires-python.*$/requires-python = ">=3.11"/' pyproject.toml   # 修改项目的python依赖为 >= 3.11

$ poetry env use 3.11  # 切换 Python 3.11
Creating virtualenv app-X2aZMY7n-py3.11 in ~/.cache/pypoetry/virtualenvs
Using virtualenv: ~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.11
$ poetry run python --version   # 验证当前 Python 版本
Python 3.11.14

$ poetry env use 3.13  # 切换 Python 3.13
Creating virtualenv app-X2aZMY7n-py3.13 in ~/.cache/pypoetry/virtualenvs
Using virtualenv: ~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.13
$ poetry run python --version   # 验证当前 Python 版本
Python 3.13.5

$ poetry env info --path   # 虚拟环境的路径
~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.13

$ poetry env list
app-X2aZMY7n-py3.11
app-X2aZMY7n-py3.13 (Activated)   # 当前启用的 Python 版本

以上命令使用 env use 创建了 Python 3.11 和 Python 3.13 的虚拟环境，后一个虚拟环境 Python 3.13 目前处于 Activated 状态。不同版本的虚拟环境有不同的虚拟环境目录，切换不同 Python 版本很方便验证项目在各个版本上的可用性。指定的虚拟环境版本必须符合 pyproject.toml 中对 Python 依赖的规定。

虚拟环境的路径中有一串看似无意义的随机字符串（X2aZMY7n），实际是对项目路径做了 hash 之后的 base64 编码，如果项目路径发生变化，虚拟环境也会重新生成。

poetry env remove --all 删除所有虚拟环境，也可以将 --all 替换为具体的版本，删除特定版本。

$ poetry env remove --all

进入虚拟环境

在写代码或者某些场景中，可能需要进入虚拟环境操作，方法如下：

$ poetry env activate  # 查看激活虚拟环境的方法
source ~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.13/bin/activate

$ source ~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.13/bin/activate  # 激活虚拟环境
(app-py3.13) $ which python   # 检查虚拟环境
~/.cache/pypoetry/virtualenvs/app-X2aZMY7n-py3.13/bin/python

(app-py3.13) $ deactivate   # 退出虚拟环境

和正常激活虚拟环境的区别不大，主要是找到当前的虚拟环境路径。

运行测试项目

开发流程中的 Poetry

在使用 Poetry 管理的项目中，开发流程中常涉及的管理动作如下： + poetry new 创建项目。 + poetry add/remove 管理项目依赖 + 开发项目 + poetry run 运行和测试项目 + poetry sync 更新本地的依赖情况

一般来说，pyproject.toml 文件中的某些信息也是需要偶尔手动维护的。

实例

新建项目

$ poetry new simple-web --flat
$ cd simple-web
$ poetry add flask

修改 app/__init__.py 文件为如下内容，是一个最简单的 Flask Web 应用：

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, World"

运行方法：

$ FLASK_APP=app:app poetry run flask run

小结

Poetry 把依赖管理、虚拟环境与构建发布整合到统一流程中，使用门槛低、可重复性强。对应用型项目，建议优先明确依赖组与 Python 版本约束；对库项目，则更应关注依赖范围与锁定策略的边界。值得关注的是，Poetry 之外还有势头正猛的后起之秀 uv，将在下一篇博客中介绍。

OpenTelemetry 和 Flask

Sun, 28 Dec 2025 16:21:45 +0800

在上一篇文章 OpenTelemetry 入门和部署中介绍了 OpenTelemetry的架构，并部署了一套极简的OpenTelemetry服务。在上一篇文章的最后，我们使用curl向OpenTelemetry Collector服务的HTTP接口上报了Traces、Metrics和Logs数据，并进行了验证。本文将从测试场景进入到应用场景，编写两个基于Flask的Web服务，看看在Python Web开发场景中，如何将应用的Traces、Metrics和Logs数据上报到OpenTelemetry。

如果还不了解OpenTelemetry，请先移步上一篇文章 OpenTelemetry 入门和部署，了解OpenTelemetry的相关架构和原理。本文主要探索SDK端的用法，各个后端平台还是使用上一篇文章中搭建的OpenTelemetry服务。

项目初始化

OpenTelemetry的Python SDK文档：https://opentelemetry.io/docs/languages/python/getting-started/

OpenTelemetry官方也提供了一个包含十几个微服务的测试项目，分别用十几种语言实现，详情参考 OpenTelemetry Demo ，比较复杂，可以在遇到问题时查看和参考。

本案例中的各个软件版本： OS：Debian 13 Python： 3.13.5 Flask：3.1.2

本测试项目受OpenTelemetry文档中的骰子项目启发，将其改造为2个HTTP服务，形成调用关系，方便我们观察跨微服务的链路跟踪。

使用uv做项目管理，在项目中包含两个Python源码文件，分别是 dice-app.py 和 dice-backend.py ，前者通过HTTP方法调用后者，分别上报各自的指标到OpenTelemetry。

$ uv init . --name dice
$ uv add flask

dice-backend应用

创建一个简单的Flask应用——摇骰子，功能是在sqlite3数据库执行 select random()命令，然后把取得的数字对7做取模操作，获得余数作为骰子点数，如果点数在1~6之间则返回，否则抛出ValueError异常。dice-backend.py 的代码如下：

from flask import Flask
import logging
import sqlite3
from opentelemetry import metrics, trace

app = Flask(__name__)
tracer = trace.get_tracer(__name__)
meter = metrics.get_meter(__name__)

cnx = sqlite3.connect(":memory:", check_same_thread=False)
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
roll_counter = meter.create_counter(    # 定义Counter类型的指标
    "dice_number_counter",
    description="The number of rolls by roll value",
)

@app.route("/rolldice")
def roll_dice():
    number = roll()
    logger.info(f"random dice number: {number}")
    return str(number)

def roll():
    with tracer.start_as_current_span("roll") as roll_span:   # 手工插桩
        cursor = cnx.cursor()
        number = cursor.execute("select random()").fetchone()[0]
        cursor.close()
        roll_span.set_attribute("origin_random_number", number)   # 设置span的属性
        logging.info(f"raw number from sqlite3 is {number}")    # 在 span 上下文记录的日志会携带 trace_id 等字段

    if (ret := int(number) % 7) in range(1, 7):       # 骰子点数必须在1-6之间
        roll_counter.add(1, {"roll.value": ret})      # 对metric进行设置
        return ret
    raise ValueError(f"dice must in (1, 6), given: {ret}")

代码的内容非常简单，特殊的地方在于手动添加了2个OpenTelemetry的数据上报点。第1个是把从sqlite3中取出的数据设置到trace的origin_random_number这个属性中。第二个是metrics的统计功能，对骰子点数出现的次数进行+1操作，用于统计骰子每个点数出现的次数。

代码中使用 with tracer.start_as_current_span("roll") as roll_span: ...做了手动插桩，这是链路跟踪的常见操作，创建了名为roll的span，span是分布式系统中单个操作的执行记录，包含开始时间、持续时间、状态和元数据等信息。在这个span的上下文内，我们为span添加了一个属性（使用set_attribute函数），记录执行过程中的信息。

span是分布式链路追踪（Distributed Tracing）领域的通用术语。在分布式系统中，一次请求的完整路径被称为 Trace（追踪），而路径上的每一个逻辑节点（比如一次数据库查询、一次 RPC 调用、一次函数执行）都被形象地称为 Span（跨度）。之所以叫“跨度”，是因为它代表了：时间的跨度，从操作开始（Start Time）到结束（End Time）的时间区间；逻辑的跨度，在复杂的拓扑图中，它是连接两个组件的“桥梁”。在SkyWalking和Zipkin等跟踪系统中均有此术语。

另外，这个代码有个明显的bug，骰子有1/7的概率结果为0, 触发ValueError的异常。

对于上报的logs数据来说，在span上下文中记录的日志在OTLP协议上报时会被附上trace_id等字段，在问题排查时，可以把日志中的trace id和链路跟踪系统中的trace id对应起来综合排查。

运行和测试

OpenTelemetry提供了对常见Python库的自动插桩（Instrumentation）支持，比如Flask、sqlite3、logging、httpx等，官方支持的一些Python库，见文档 Instrumentation 。

在这个项目中，我们使用OpenTelementy为Python提供的自动插桩工具，并为代码中使用到的库安装opentelemetry提供的专用SDK。

安装依赖：

$ uv add opentelemetry-instrumentation \
    opentelemetry-distro \
    opentelemetry-exporter-otlp \
    opentelemetry-instrumentation-sqlite3 \
    opentelemetry-instrumentation-flask \
    opentelemetry-instrumentation-logging

安装完依赖后使用自动插桩的方法运行dice-backend.py应用：

$ OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" \
FLASK_APP=dice-backend.py \
opentelemetry-instrument \
    --traces_exporter otlp \
    --metrics_exporter otlp \
    --logs_exporter otlp \
    --service_name dice-backend \
    uv run flask run -p 5001

环境变量OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED 设置启用日志库的自动插桩。
环境变量OTEL_EXPORTER_OTLP_ENDPOINT 指定了OpenTelemetry的GRPC地址为本机的 http://localhost:4317，也就是上一篇文章中在本地搭建的Opentelemetry服务。
环境变量FLASK_APP 指定了 flask项目的文件。
opentelemetry-instrument命令是自动插桩用的，参数中指定了 traces、metrics和logs的exporter类型为otlp。表示将数据上报到OpenTelemetry。其实exporter的类型很丰富，调试时也常常把exporter设置为console输出到命令行，比如 --traces_exporter console ，也支持同时设置多个exporter，比如 --traces_exporter otlp,console。--service_name 参数指定了应用标识为dice-backend，OTLP上报时被转换为 service.name字段。
使用uv环境和flask run命令运行项目，并监听在5001端口。

反复运行下面的curl命令对dice-backend服务进行测试

$ curl http://localhost:5001/rolldice

多次请求这个接口，大概有1/7的可能性会返回 500 INTERNAL SERVER ERROR 报错。正常的时候应该都会返回1～6之间的数字。

打开Jaeger的ui http://127.0.0.1:16686，查看dice-backend应用的traces数据，点进细看请求的链路的树形结构，会看到3个span，分别是：
- 对sqlite的自动插桩，内容是执行的SQL语句；
- 对roll函数的手动插桩，内容是select randome()语句的执行结果；
- 对flask的自动插桩，记录HTTP请求参数；
- 以上3个span有各自的span id，却有共同的trace id
当接口报错时，在Jaeger上可以看到具体的异常报错
打开Prometheus的ui http://127.0.0.1:9090，搜索 dice_mumber_counter_total 指标的结果，查看骰子的每个点数出现的次数。
- 此外，还有 http_server_* 等OpenTelemetry的flask库内置指标
打开Elasticsearch 的 http://127.0.0.1:9200/logs-dice-backend/_search，查看上报的日志，能看到flask输出的access log。

三个平台的数据之间有一些共同的字段，比如 server.name（prometheus中一般是service_name），traces和logs中也可能有共同的trace_id。

使用Opentelemetry提供的自动插桩功能就能实现对常见库调用的traces数据收集，也很方便的手动对函数做插桩，实现自定义指标数据上报。这是开发中的一种常见做法，不用对代码进行大面积改动。

接下来实现dice项目的app服务，在该服务中，将完全使用代码进行opentelemetry各个exporter的初始化。

dice-app 应用

在 dice-app 服务中，将用httpx库批量调用dice-backend服务的HTTP接口，获取骰子点数，用jinja2渲染为Web页面。功能也很简单。dice-app.py文件的代码如下：

from flask import Flask, request
import logging
import httpx
import jinja2

##### OpenTelemetry 的初始化: traces、logs、metrices
from opentelemetry import trace, metrics
from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor  # ConsoleSpanExporter
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import (
    BatchLogRecordProcessor,
)  # ConsoleLogExporter,
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.sdk.metrics.export import (
    PeriodicExportingMetricReader,
)  # ConsoleMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.jinja2 import Jinja2Instrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor  # noqa
from opentelemetry.instrumentation.logging import LoggingInstrumentor

OTLP_EXPORTER_ENDPOINT = "http://127.0.0.1:4317"
resource = Resource.create({SERVICE_NAME: __name__, SERVICE_VERSION: "1.0.0"})

trace_provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(endpoint=OTLP_EXPORTER_ENDPOINT, insecure=True)
trace_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
trace.set_tracer_provider(trace_provider)

logger_provider = LoggerProvider(resource=resource)
log_exporter = OTLPLogExporter(endpoint=OTLP_EXPORTER_ENDPOINT, insecure=True)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(log_exporter))
handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
logging.getLogger().addHandler(handler)
logging.getLogger().addHandler(logging.StreamHandler())

meter_exporter = OTLPMetricExporter(endpoint=OTLP_EXPORTER_ENDPOINT, insecure=True)
meter_reader = PeriodicExportingMetricReader(
    meter_exporter,
    export_interval_millis=15000,  # metrics 每15s更新
)
meter_provider = MeterProvider(resource=resource, metric_readers=[meter_reader])
metrics.set_meter_provider(meter_provider)

tracer = trace.get_tracer(__name__)
meter = metrics.get_meter(__name__)

Jinja2Instrumentor().instrument()
HTTPXClientInstrumentor().instrument()
LoggingInstrumentor().instrument()

##### OpenTelemetry 的初始化结束

access_counter = meter.create_counter(
    "access_times",
    description="index accesse times",
)

app = Flask(__name__)

logger = logging.getLogger(__name__)
FlaskInstrumentor().instrument_app(app)   # 对Flask应用进行插桩


@app.route("/")
def roll_dice_index():
    client_ip = str(request.remote_addr)
    with tracer.start_as_current_span("get_client_ip") as client_span:
        client_span.set_attribute("client_ip", client_ip)

    access_counter.add(1)
    template = jinja2.Template("""<ul>
        {% for j in data %}
        <li>{{j}}</li>
        {% endfor %}
    </ul>""")

    with httpx.Client() as client:
        data = [client.get("http://127.0.0.1:5001/rolldice").text for _ in range(2)]

    return template.render(data=data)

上面的代码看着很多，近80行。但实现的功能挺简单的，都集中在roll_dice_index这一个简单的flask视图函数中：

直到app = Flask(__name__) 之前，大部分的代码都是在设置OpenTelemetry指标上报相关的功能。忽略掉import语句，这部分内容主要做了如下工作：
- 定义上报的OpenTelemetry的目标地址为 "http://127.0.0.1:4317" 。
- 创建resource，其中的字段会作为属性一起上报给OpenTelemetry。
- 初始化traces、logs和metrics实例。初始化步骤其实差不多，都是定义provider、定义基于GRPC的exporter、将exporter关联到provider上，将provider设置给全局的traces、metrics和logging。
- 对于项目中用到的httpx、jinja2、logging、flask库进行自动化插桩库的启动。
- 创建了一个名为 access_times 的counter类型指标，用于统计主页被访问的次数。
- 创建了两个钩子函数request_hook 和 response_hook，分别记录用户对这个服务的请求和响应的内容。
实例化Flask对象后，对flask应用进行插桩，关联了上面定义的两个钩子函数。
本案例代码中的手动插桩函数在dice-backend 项目中都见过了，不做详细介绍了。
在完全使用代码实现的插桩方式中，也可以引入console或者file类型的exporter。

OpenTelemetry初始化和业务代码混在一起，上面的代码看着有点吓人。在实际的项目中，一般会将OpenTelemetry的初始化代码放到独立的模块中，避免影响业务代码的整洁度。

运行和测试

这个项目中用到了httpx和jinja2模块，安装相关依赖和自动插桩库。

$ uv add httpx \
    opentelemetry-instrumentation-jinja2 \
    opentelemetry-instrumentation-httpx

在代码中初始化OpenTelemetry的场景下，使用常规的方法启动flask应用就行，监听到5000端口。

$ FLASK_APP=dice-app.py uv run flask run -p 5000

反复执行下面的命令。

$ curl http://127.0.0.1:5000/

查看相关的上报数据：

Jaeger中可以看到调用链路了，总共12个span，6个来自dice-app应用，另外6个来自dice-backend（对dice-backend调用了2次，每次3个span），在dice-app中的6个span分别是：
- flask自动插桩，记录请求和响应；
- get_client_ip 手动插桩，记录请求者的ip地址。其实在flask的插桩中已经有了，没有什么实际价值。
- 来自jinja2的jinja2.compile 和jinja2.render的函数自动插桩。
- 2次httpx的自动插桩。记录请求和响应的http_code。
Prometheus：查看指标access_times_total
打开Elasticsearch 的 http://127.0.0.1:9200/logs-dice-app/_search，查看上报的日志，能看到flask输出的access log。

为什么dice-app和dice-backend 应用使用同一个trace_id？因为，我们引入了httpx库的OpenTelemetry插桩，在使用httpx向dice-backend发起请求的时候，httpx在请求的header中，自动包含了trace id字段。

可以看到，即使代码中没有手动添加flask、jinja2和httpx的插桩代码，因为安装了这3个库的OpenTelemetry插桩库，使得相关的trace能够自动创建和采集。非常方便。

OpenTelemetry的flask 和 httpx等许多插桩库都有钩子功能（request_hook和response_hook），可以记录请求和响应的特定字段，有兴趣的查看各个OpenTelemetry的对应库的文档做详细了解。

总结

本文通过2个实际的Flask案例展示在Python开发中的2种不同的OpenTelemetry接入方法，可以从中一窥OpenTelemetry提供的强大能力。开发中，记得常看看OpenTelemetry的官方和依赖库文档，往往有意想不到的收获。

OpenTelemetry正变得越来越流行，OpenTelemetry的跨语言、跨框架的traces、metrics、logs采集和处理能力，能为我们的应用带来十分不错的可观测性收益。开发者可以据此构建更加透明和可控的分布式系统，提高应用的可观测性，从而更快地定位和解决问题。

OpenTelemetry 入门和部署

Sun, 14 Dec 2025 22:51:12 +0800

在维护现代分布式系统时，了解服务的运行状况和进行错误分析往往充满挑战。当客户请求横跨多个微服务、函数和基础设施时，如何能够清晰地洞察整个请求链路的健康状况与性能表现？这个问题的答案，就在于完善的服务可观测性。

可观测性不仅仅是传统的监控（记录已知的故障模式），它赋予我们通过系统外部输出来探索、分析和理解系统内部状态的能力。这通常建立在三大支柱之上：指标（Metrics）、链路（Traces） 和日志（Logs）。

OpenTelemetry简介

在传统的可观测性实践中，应用程序需要分别使用不同的SDK对接各种监控平台，如Prometheus用于指标监控、Jaeger用于链路跟踪、Elasticsearch用于日志处理。在异构技术栈并存的微服务环境中，如何以一种统一、标准化的方式采集和关联这些运行数据，是一个复杂的难题。正是在这样的背景下，OpenTelemetry（简称OTel） 应运而生。它是一个由云原生计算基金会（CNCF）托管的开源项目，旨在提供一套与供应商无关的、统一的API、SDK和工具集，用于采集和导出遥测数据。

使用OpenTelemetry，实现可观测性目标的过程被大大简化。应用程序只需要对接OpenTelemetry，SDK将指标发送给OpenTelemetry，然后OpenTelemetry会负责进行数据处理，并转发给Prometheus、Jaeger和Elasticsearch等服务。OpenTelemetry的主要目标之一就是让任何编程语言、基础设施和运行环境中的应用程序和系统都易于进行观测。

具体来说，OpenTelemetry解决了3个核心问题：

定义一套标准——OTLP协议：OpenTelemetry Protocol (OTLP) 是OpenTelemetry项目定义的一种通用遥测数据传递协议。OTLP旨在为遥测数据（包括Traces、Metrics和Logs）的编码、传输和传递提供一个标准化的机制。它定义了数据从遥测源（如应用程序的SDK）到中间节点（如OpenTelemetry Collector收集器），再到最终遥测后端（如存储和分析系统）的整个过程，实现了标准化、高效性和通用性的metrics、traces、logs数据传递。OTLP推荐并主要使用Protocol Buffers (Protobuf)进行数据的序列化和gRPC传输，也支持其他序列化和HTTP传输方式。OTLP是OpenTelemetry生态系统的"通用语言"，它通过定义标准的数据格式和传输机制，极大地简化了可观测性数据的采集和互操作性。
适配不同编程语言和框架的SDK：OpenTelemetry为各种主流编程语言（如Java、Go、Python、JavaScript等）提供了官方实现的SDK。开发者只需使用对应语言的SDK进行简单集成，就能自动或手动地从应用程序中采集遥测数据，并将其转换成符合OTLP标准的格式。这极大地简化了开发者的接入成本。
指标采集和处理服务——OpenTelemetry Collector：这是一个独立运行的代理服务，是OpenTelemetry架构中的"智能枢纽"。应用程序将OTLP格式的数据发送到Collector，由它来统一负责后续繁重的工作，例如：
- 接收与转发：接收来自多个应用的数据，然后批量转发给一个或多个后端平台。
- 处理与加工：对数据进行清洗、过滤、采样或富化（添加额外的标签信息）。
- 格式转换：将OTLP数据转换成其他后端系统支持的格式（如Jaeger的格式、Prometheus的格式等）。

基于以上三点，OpenTelemetry构建了一个标准化的、端到端的、高性能的遥测数据采集与处理管道。

下图展示了OpenTelemetry的可观测性架构：

可以看到，OpenTelemetry提供了各类语言的SDK用于对接OpenTelemetry，也提供了中间用于数据处理和转发的OpenTelemetry Collector工具。而数据最终的归属，依旧是大家常用的那些Elasticsearch和Prometheus等平台。OpenTelemetry就像一座桥梁，左边连接应用软件，右边连接各个可观测平台，它提供的统一SDK和数据处理工具大大降低了对接的复杂性。

接下来我们将搭建一套极简版本的OpenTelemetry架构，基于以下的基础环境：

OS：Debian 13
Docker：docker-ce 29.1.2

OpenTelemetry部署

接下来使用Docker Compose部署一套基本可用的OpenTelemetry服务，包括以下4个服务：

OpenTelemetry Collector：接收应用程序发送过来的链路跟踪、指标和日志数据等，并处理和转发到各个后端服务。
Jaeger：2.12.0版本，接收OpenTelemetry Collector发送过来的OTLP标准的跟踪数据，提供链路跟踪和可视化查询能力。
Prometheus：接收OpenTelemetry Collector发送过来的metrics，提供指标存储和查询的能力。
Elasticsearch：8.19.7版本，作为存储后端，本案例中有两个作用，一方面用于保存OpenTelemetry Collector发送过来的日志，另一方面作为Jaeger的后端存储服务。

本文使用了比较常见的技术栈，实际上，在OpenTelemetry的生态系统中，有大量支持OTLP协议的服务可以替换上述各组件。此处不再一一赘述，详细清单可参见官方文档。

Docker Compose配置

为了简化部署，本文使用Docker Compose的方式部署4个服务。compose.yml的内容如下：

services:
  jaeger:
    image: jaegertracing/jaeger:2.12.0
    container_name: jaeger
    command:
      - "--config=file:/etc/jaeger/jaeger.yml"
    volumes:
      - ./conf/jaeger.yml:/etc/jaeger/jaeger.yml
    ports:
      - 16686:16686  # HTTP UI
      - 14317:4317   # GRPC
      - 14318:4318   # HTTP
    depends_on:
      elasticsearch:
        condition: service_healthy

  prometheus:
    container_name: prometheus
    image: prom/prometheus
    user: 1000:1000
    command:
      - --web.enable-otlp-receiver
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus/data/
    volumes:
      - ./conf/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./prom_data/:/prometheus/data/
    ports:
      - 9090:9090

  elasticsearch:
    image: elasticsearch:8.19.7
    container_name: elasticsearch
    restart: always
    environment:
      - cluster.name=elasticsearch
      - "ES_JAVA_OPTS=-Xms1g -Xmx1g"
      - discovery.type=single-node
      - xpack.security.enabled=false
      - xpack.security.enrollment.enabled=false
    ports:
      - "9200:9200"
    volumes:
      - ./es_data:/usr/share/elasticsearch/data
    healthcheck:
      interval: 5s
      retries: 60
      test: curl --fail -s -o /dev/null http://127.0.0.1:9200/

  otel-collector:
    image: ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.142.0
    container_name: otel-collector
    command:
      - --config=/etc/otelcol-config.yml
    volumes:
      - ./conf/otelcol-config.yml:/etc/otelcol-config.yml
    ports:
      - 4317:4317   # GRPC
      - 4318:4318   # HTTP
    depends_on:
      elasticsearch:
        condition: service_healthy
      jaeger:
        condition: service_started

上面的compose.yml文件看起来较长，但仔细观察会发现每个容器的配置都十分精简且易于理解，建议仔细阅读。

Jaeger配置解释

在上面定义的compose.yml中，Jaeger项目作为一个trace后端，接收trace类型的遥测数据，并提供对这些数据的处理、聚合、数据挖掘和可视化功能。

容器功能：

容器内监听4317和4318端口，映射到宿主机的14317和14318，避免与otel-collector监听的端口产生冲突。
16686端口提供Jaeger的Web UI服务，用于查看应用的trace链路。
Jaeger会将trace数据保存到Elasticsearch服务中，所以需要依赖Elasticsearch先启动。
本地的conf/jaeger.yml文件保存Jaeger的配置文件，里面定义了数据的接收和发送方式。

conf/jaeger.yml配置文件的内容如下，基于Jaeger v2版本：

extensions:
  jaeger_query:
    storage:
      traces: myes_storage
      metrics: myes_storage
    base_path: /jaeger/ui

  jaeger_storage:
    backends:
      myes_storage: &elasticsearch_config
        elasticsearch:
          server_urls:
            - http://elasticsearch:9200
          indices:
            index_prefix: "jaeger-main"

    metric_backends:
      myes_storage: *elasticsearch_config

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  jaeger_storage_exporter:
    trace_storage: myes_storage

service:
  extensions: [jaeger_storage, jaeger_query]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger_storage_exporter]

配置说明：

extensions: 定义了jaeger_query和jaeger_storage两个扩展，前者配置了Jaeger的Web UI功能，后者是Jaeger的存储功能。存储功能中又配置了trace存储和metric存储，都使用Elasticsearch服务保存。在myes_storage中配置了Elasticsearch服务的API地址和使用的indices名字前缀。
receivers: 指定Jaeger作为接收者，监听gRPC和HTTP端口。otel-collector和应用可以把trace数据发往这两个端口。
processors: Jaeger具有处理指标的能力，这里仅配置了常用的batch处理器。
exporters: 定义了将数据发送到Elasticsearch存储服务中。
service: 引用了extensions、receivers、processors、exporters的配置。重要的是pipelines中的管道，配置了从OTLP协议接收traces数据，发送到exporter配置中定义的Elasticsearch存储服务。

上面配置的基本含义是：通过OTLP协议在4317 (gRPC) 和4318 (HTTP) 端口接收trace数据，使用批处理器对数据进行批量处理，通过exporter将数据存储到Elasticsearch，Jaeger Query扩展从相同的Elasticsearch后端读取数据并在Web UI展示。

Jaeger的OTLP端口和OpenTelemetry Collector一样，在同一个主机上监听相同的端口号会有冲突。如果修改Jaeger的端口号，会导致Jaeger的自身指标采集报错，虽然可以用环境变量OTEL_TRACES_SAMPLER=always_off禁用Jaeger的自监控，但是不建议这么做。

Jaeger的官方文档内容相对较少：https://www.jaegertracing.io/docs/2.12/ Jaeger仓库中的参考配置案例：https://github.com/jaegertracing/jaeger/tree/v2.12.0/cmd/jaeger

Prometheus配置解释

Prometheus一般使用Pull模式拉取指标，但它也支持作为OTLP接收器。打开CLI标志--web.enable-otlp-receiver后，就可以在Prometheus的/api/v1/otlp/v1/metrics路径上提供OTLP指标接收服务。

在Prometheus的Docker定义中做了如下配置：

启用--web.enable-otlp-receiver CLI flag，开启Prometheus的OTLP指标接收功能。OpenTelemetry Collector会往这个服务发送metrics数据。
另外将本地的conf/prometheus.yml配置文件和prom_data目录映射到容器中，映射prom_data目录用于提供数据持久化的能力。
Prometheus的9090端口提供接收指标和UI查询功能，暴露到主机上。

Prometheus配置文件conf/prometheus.yml：

global:
  scrape_interval: 15s

otlp:
  keep_identifying_resource_attributes: true
  promote_resource_attributes:
    - service.instance.id
    - service.name
    - service.namespace
    - service.version
    - deployment.environment.name

Prometheus的配置相对简单：

配置OTLP接收器处理来自应用程序的遥测数据
将service.name、service.instance.id等资源级别的属性提升为指标标签，便于查询和筛选。

Prometheus一般作为指标存储服务，常与Grafana可视化平台搭配使用，简单起见，本文不涉及Grafana的内容。

Elasticsearch配置解释

Elasticsearch提供日志存储和查询功能，可视化的查询服务需要部署Kibana。关于Kibana服务的内容，在之前的文章EFK日志体系快速入门中已经有所提及，为了简化演示，本次就不部署Kibana了。如果部署Kibana，要保持Kibana和Elasticsearch的版本一致。

由于Jaeger官方文档指定支持Elasticsearch的7.x和8.x版本，所以没有使用最新的Elasticsearch 9.x版本。

在compose.yml文件中，对Elasticsearch做了如下的简单配置：

关闭了Elasticsearch安全功能，免去配置用户名和密码的麻烦。这种操作仅限于测试环境。
Elasticsearch的数据映射到es_data目录下，实现存储数据持久化。

OpenTelemetry Collector配置详解

OpenTelemetry Collector的Docker相对简单，主要是将接收数据的端口4317（gRPC）和4318（HTTP）暴露出来用于应用上报数据。

conf/otelcol-config.yml配置文件的内容如下，定义了数据接收、处理和转发的逻辑：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 2s
    send_batch_size: 1000

  transform:
    log_statements:
      - statements:
        - set(log.attributes["elasticsearch.index"], Concat(["logs", resource.attributes["service.name"]], "-"))

exporters:
  otlp:
    endpoint: "jaeger:4317"
    tls:
      insecure: true
  otlphttp/prometheus:
    endpoint: "http://prometheus:9090/api/v1/otlp"
    tls:
      insecure: true
  elasticsearch:
    endpoint: "http://elasticsearch:9200"
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: []
      exporters: [otlphttp/prometheus]
    logs:
      receivers: [otlp]
      processors: [batch, transform]
      exporters: [elasticsearch]

otel-collector的配置文件和Jaeger有相似的结构，这套配置文件中定义了如下3个部分：

receivers：otel-collector监听的gRPC和HTTP服务端口，应用程序可以往这些端口上发送数据。
processors：创建了batch和transform 2个processor：
- batch：批量处理数据，提升处理效率。
- transform：为日志数据新增了elasticsearch.index 这个属性，格式是 logs-${service.name}，service.name是客户端上报的属性名字。Elasticsearch会根据 elasticsearch.index的值自动创建索引。如此，就实现了不同应用使用不同索引的需求。transform proccessor 十分有用，可以很方便对日志元数据和内容进行编辑。
exporters：otel-collector将把数据发往这些后端服务，分别是Jaeger、Prometheus和Elasticsearch服务。
service：定义了数据处理的pipeline，trace类型的指标发往Jaeger、metric的指标发往Prometheus、日志类型的数据发往Elasticsearch。

OpenTelemetry Processor 文档中可以查看所有的各类processor。有需要的请前往了解。

Note：Elasticsearch Exporter默认使用 Data Stream 将数据发送到Elasticsearch，Data Stream 类型的索引的前缀一般是 .ds- ，十分合适存储只会append数据的存储场景。使用Data Stream类型时，发送给Elasticsearch的索引（即elasticsearch.index属性）必须是 logs-、metrics-或者traces-为prefix的，否则 Elasticsearch会返回报错index_not_found_exception。如果要自定义非Data Stream 格式的索引名字，必须显式的关闭Data Stream，方法为 elasticsearch.mapping::mode = none。这个地方踩了很久的坑，有太多隐藏的约定，值得注意。

数据的处理和存储形态可能是多种多样的，比如可能有Kafka消息队列应对大规模并发；也可能仅使用Elasticsearch技术栈，毕竟Elasticsearch+Kibana几乎可以承担所有的Trace、Metric和Log的存储、处理和展示。这里展现的只是一种常见的组合方式，而OpenTelemetry的强大之处也在于对各类平台的广泛支持。

另外，为了叙述方便，文中的Docker和各平台的配置都做了极简化的处理，能运行起来。但省略了安全、性能等方面的优化，在正式使用时，还需要再读读文档，对配置进行与环境适配性的改造。

启动服务

确保上面的compose.yml和conf/jaeger.yml、conf/prometheus.yml、conf/otelcol-config.yml文件已经都创建好了。

启动前先创建Elasticsearch和Prometheus的数据持久化目录：

$ mkdir es_data
$ mkdir prom_data
$ sudo chown -R 1000:1000 es_data prom_data

$ docker compose up -d

测试验证

虽然现在还没有开发上报数据的应用，但是Jaeger自身的指标也会被采集和发送到OpenTelemetry Collector，打开Jaeger的Web UI界面，多刷新几次就能看到Jaeger自身的trace数据了。

接下来使用curl命令向OpenTelemetry Collector的HTTP端口发送各类简单的测试数据。

测试Traces功能

向otel-collector上报一条trace数据，构造一条模拟耗时10s的trace数据（startTimeUnixNano和endTimeUnixNano相差10s）：

$ curl -X POST http://localhost:4318/v1/traces   -H "Content-Type: application/json"   -d '{
  "resourceSpans": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "test-service"}
      }]
    },
    "scopeSpans": [{
      "spans": [{
        "traceId": "'$(openssl rand -hex 16)'",
        "spanId": "'$(openssl rand -hex 8)'",
        "name": "curl-test-span",
        "kind": 1,                                    
        "startTimeUnixNano": '"$(date --date='10 seconds ago' +%s%N)"',
        "endTimeUnixNano": '"$(date +%s%N)"',
        "attributes": [{
          "key": "test.attribute",
          "value": {"stringValue": "42"}
        }]
      }]
    }]
  }]
}'

打开Jaeger的Web UI地址为http://127.0.0.1:16686，在打开页面的Service下拉框中应该能选中test-service，然后点击Find Traces按钮，右侧就能看到刚刚上报的trace的详情了。其中的duration显示为10s。

测试Metrics功能

向otel-collector上报一条测试的metric数据：

$ curl -X POST http://localhost:4318/v1/metrics   -H "Content-Type: application/json"   -d '{
  "resourceMetrics": [{
    "resource": {
      "attributes": [{
        "key": "service.name", 
        "value": {"stringValue": "test-service"}
      }]
    },
    "scopeMetrics": [{
      "metrics": [{
        "name": "curl_test_gauge",
        "gauge": {
          "dataPoints": [{
            "timeUnixNano": '"$(date +%s%N)"',
            "asInt": "42"
          }]
        }
      }]
    }]
  }]
}'

打开Prometheus的Web UI，本机地址为http://127.0.0.1:9090，在输入框中填入指标名curl_test_gauge并搜索，就能看到指标了。提交数据中的属性service.name在Prometheus中对应了service__name="test-service" label。

测试Logs功能

向otel-collector上报一条日志数据：

$ curl -X POST http://localhost:4318/v1/logs -H "Content-Type: application/json" -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [{
          "key": "service.name",
          "value": { "stringValue": "test-service" }
        }]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s%N)'",
          "severityText": "ERROR",
          "body": { "stringValue": "error occurred" }
        }]
      }]
    }]
  }'

查看Elasticsearch的indices和数据，省略了其中uuid的信息：

$ curl 127.0.0.1:9200/_cat/indices?v  # 查看索引
health status index                                     uuid pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   jaeger-main-jaeger-service-2025-12-14     ...   5   1         13            0     41.9kb         41.9kb       41.9kb
yellow open   .ds-logs-test-service-2025.12.14-000001   ...   1   1          1            0      5.8kb          5.8kb        5.8kb
yellow open   jaeger-main-jaeger-span-2025-12-14        ...   5   1        335            0    208.4kb        208.4kb      208.4kb

$ curl http://127.0.0.1:9200/logs-test-service/_search | jq .   # 查看index中的日志
...

查看indices时，jaeger-main-*格式的index是Jaeger发送过来的trace数据。

而.ds-logs-test-service.*格式的是应用通过 otel-collector发送的日志数据，其中的doc数量是1，就是我们刚刚上报的一条日志。

在proccessor.transform中设置的elasticsearch.index 明明是 logs-${service.name}，现在为什么变成了 .ds-logs-test-service.* ？这个index名字可能有点奇怪，原因在于 logs-${service.name}的index格式匹配了Elasticsearch的内置模板，名字为 logs，会导致所有 logs-*-*的索引都保存为 Data Stream格式，并且添加日期后缀。可以通过Elasticsearch的 /_index_template/logs接口查看这个模板的信息。

具体可以参考 Elasticsearch Exporter。

到此为止，OpenTelemetry的各个组件部署和测试就完成了。

Elasticsearch的Data Stream

在测试OpenTelemetry对接Elasticsearch是才第一次遇到Data Stream，解决了许多问题，这里对Data Stream做个介绍。

Data Stream在Elasticsearch 7.9版本中引入，用于优化时序数据(如Logs、Traces和Metrics）的存储，这类数据的特点是经常append，但是不会update、insert。Data Stream因此能更高效的处理时间范围过滤。当我们创建 logs-test-service这个Data Stream时，Elasticsearch会自动创建索引.ds-logs-test-service-2025.12.14-000001。这个索引的各字段含义为：

.ds-：固定前缀，表示这是 Data Stream 的后端索引，一个Data Stream索引可能由多个这样的后端索引构成，分散的存储数据。
- .开头的索引被视为隐藏索引（Hidden Indices）。
- 不要手动向.ds-索引进行数据增删改操作。不要手动删除.ds-索引。
- .ds-索引应该由ILM（索引生命周期管理）自动化管理，ILM可以通过/_ilm/policy/logs查看。
- 用户应该始终使用logs-test-service，而不是使用.ds-logs-test-service-* 。
logs-test-service：定义的 Data Stream 名字。Data Stream 不是独立存在的，它必须匹配一个“开启了 Data Stream 功能”的索引模板。比如logs-test-service就符合logs索引模板的 pattern (logs--)。
2025.12.14：该索引创建时的日期。
000001：代际号（Generation）。这是一个 6 位填充的数字，从 000001 开始，每当发生一次 Rollover（滚动），这个数字就会加 1。rollover的时机可能是index的大小或者文档数量达到设定的阈值了。

以下是和 Data Stream相关的一些操作：

GET /_data_stream：查看所有数据流
GET /_data_stream/logs-test-service：查看特定数据流的详细信息
GET /_data_stream/_stats：查看数据流统计信息
POST /logs-test-service/_rollover：手动rollver，产生新的后端索引

此外，每次往data stream中写入数据时，必须指定为create index操作。比如

$ curl -X POST 'http://127.0.0.1:9200/_bulk?pretty'  -H "Content-Type: application/json" \
  -d '{"create":{"_index":"logs-test-service"}}
{"body":{"text":"error occurred"}}
'

Data Stream还有一个好处，在Kibana上创建data view时，可以直接指定 Data Stream的名字logs-test-service，而不需要使用 logs-test-service-*这种传统的索引匹配方法。

小结

本文中，我们首先介绍了OpenTelemetry通过制定标准、统一接入的方式，优化了可观测性方面的难题。然后，使用Docker部署了一套常见的OpenTelemetry架构。最后，我们使用curl工具向OpenTelemetry Collector的HTTP端口分别上报Traces、Metrics和日志数据，并进行逐一验证。

为了方便展示，文中的配置都是极简的，仅限于测试，在真正用于生产环境之时，以上所有的配置文件，甚至整体架构方面都有大量可以优化的地方。

在下一篇文章中，将使用Python的Flask框架，分享如何在应用程序中集成OpenTelemetry的SDK，并向OpenTelemetry Collector上报数据，最终展示到各个可观测平台。

我的Linux

Sat, 22 Nov 2025 19:36:07 +0800

2025国庆节，给我的笔记本重装了Linux桌面系统，用上了Debian 13（代号Trixie），默认的桌面环境Gnome 48，本文趁机回顾下这十几年使用Linux桌面的历史，这是一段充满探索、适应与发现的旅程。

起点：Ubuntu 和 Gnome

2010年，为了学习Linux，我开始把Ubuntu作为日常系统，刚开始是Windows7 + Ubuntu 双系统，没过多久，Windows就安装到虚拟机里了。那时候还是Gnome 2，它的桌面布局很好，可定制性也强，稍微做下配置效果就非常酷。Gnome2绝对是一代经典。

再后来，Gnome 3出现了，在社区中引发了巨大的争议和分歧，并促使诞生了一些替代桌面环境。Gnome3的布局、设计等方面都不太适应。没过多久，Ubuntu也研发了它自己的Unity桌面，但比Gnome 3更难用。在没有更好选择的当时，还是继续先用着Gnome3。

2012年，用上了Gnome 3的桌面，兼容性还比较差，panel上大部分应用icon似乎都无法正常工作。

Elementary OS

在Gnome 3上坚持几年之后，发现了号称“最美Linux发行版”的Elementary OS，桌面效果细腻有质感，布局和gnome 2颇像，风格清新、简洁。试用之后就切换到当时版本代号Luna的Elementary OS。

虽然Elementary OS的设计和审美一流，比当时的Gnome 3更好用，但是我认为他们花费了太多精力在自研和打磨基础桌面工具（比如浏览器、邮件客户端、日历等等），而不是整合已有的优秀开源软件。不过，这也不是什么大问题。每次激动的安装新版本时候，总还会捐一点小钱感谢ElementaryOS开发者。

2016年，Elementary OS 系统。

Elementary OS还有几个其它的问题：

基于Ubuntu LTS 版本开发，因此，版本发布总是比Ubuntu晚了1年多。
在大版本迭代中，没有持续的激动人心和惊艳的新功能。
新冠疫情期间，开发团队内部出现分歧，导致开发人员流失。

作为工作使用的电脑，我还是力求稳定，2年一次系统升级对我来说可接受而且必要的。但Elementary OS看起来有些难以为继，只能寻找下一个平台了。

Pop!_OS

当Elementary OS可能不再可靠之后，在 distrowatch.com 选了选，看中了排名靠前的 Pop!_OS 发行版。也是基于Ubuntu的，提供了定制的GNOME桌面。

回归了Gnome桌面后发现，Gnome比许多年前已经成熟了很多，重要的是有许多优秀的插件可用。回顾这么多年，不管换什么发行版，都是基于Ubuntu的衍生版，都是最初的Gnome使用习惯。

2023 Pop!_OS，用回了Gnome桌面。

在Pop!_OS的使用体验还不错。重要的是，从Pop!_OS中看到了最新版Gnome桌面环境的可用性已经有了相当大的提升。

归宿：Debian

2023年，Debian 12 （代号 bookworm）发布，后续就直接换上了Debian 12，使用体验和其衍生版本几乎没有区别。简单的插件配置就能轻松定制一个漂亮、高效的桌面环境。使用过程稳定又可靠。

如果一切都稳定可靠，未来很长一段时间大概都会继续使用Debian 。

Thinkpad X1 Carbon

2022年以前，一直使用公司提供的ThinkPad L470，重量2kg，日常携带出门非常锻炼身体。在切换到Pop!_OS系统时，最终下定决心入手一台二手的thinkpad x1 carbon gen6（2018款）。主要看重这款设备的轻量便携：重量大约1kg，外观优雅，十分方便带出门。

来到2025年，Thinkpad x1 carbon gen6的16G内存有些不够用了，浏览器、企业微信、钉钉、飞书每一个都是内存占用大户，开启zram内存压缩也不够，经常要手动杀进程释放内存，否则就可能卡死桌面。于是给自己物色了二手的Thinkpad X1 Carbon Gen10（2022款），有32G内存。本想等着Debian 13发布之后，同步换新设备装新系统。但还没等到Debian 13发布，内存不足的问题就让人受不了。于是在5月底先买了电脑。初到手时，就感觉这个2022年的thinkpad在产品力方面相较2018款有不少倒退：

屏幕面太厚太重，单手掀开盖子有点费劲。设备整体比2018年款更厚了，2018款从各个角度看都更加纤细优美，拿着更舒服。
笔记本A面的设计更丑了，甚至logo都没对齐。后续用贴纸盖住。
底部垫高从2个圆点变成一根长条，在桌子上拖动电脑会发出尖锐刺耳的噪音。
键盘左手区域发烫，右手区域冰凉。
2018年款的显示器有2k，新款里砍掉了这个配置。

不过2022款也有好的地方，新款的笔记本的长宽比例更舒服。一段时间之后，各方面也就都适应了。

8月9号 Debian终于发布了第13个版本，代号Trixie。但直到国庆节才有时间安装新系统（相较于升级，我更喜欢干净的重装），安装之后，将扩展和配置挨个都导入回来，系统上手也非常快。

在数据迁移过程发生了一个小插曲：迁移到一半时，不小心删除了新电脑的家目录，大量已经迁移的配置和数据丢失了，有些数据找不回来了。之后赶紧把家目录做成LVM，并开启LVM快照，还是得定期做快照才行。重新配置和恢复又浪费了大约一天的假期时间。

2025 Debian 13

Gnome桌面环境

我依然偏爱Gnome桌面环境，简洁高效。但Gnome桌面的问题依旧不小，比如Gnome的API经常变动导致有些扩展在升级后失效。许多比较基础的桌面功能没有内置，需要安装扩展解决，一般需要安装好些扩展桌面才能好用起来。

新版Gnome中逐渐抛弃了panel上的后台应用icon支持，这点有些难以接受，目前Gnome 48版本还能通过扩展实现，但是部分icon的透明背景变成了黑色，十分丑陋，不知道未来的版本会如何。

Gnome开发者团队以其对简洁和统一的极致追求而闻名，有时甚至显得有些固执。在我看来，系统不应替用户决定‘什么是最好的’，而应将选择权交还给用户和应用开发者，提供更多的灵活性。”

好的变化

以我用Linux系统作为主力机的十年来说，也有许多好的趋势：比如 systemd 统一了init和服务管理，没有引入更多分裂，简直是个奇迹；Flatpak和Appimage简化了应用安装和运行；Gnome的打磨越来越细致了；Ubuntu放弃了自己的Unity桌面，回归Gnome的怀抱；许多国民级应用官方支持Linux了；硬件的兼容性越来越好；系统的稳定性也在增强。

令人担忧的方面

我个人对于X11和wayland的纷争不感兴趣，但是每次尝试切换到wayland之后，有些快捷键需要手动设置，投屏会出现黑屏。这些问题很让人困扰。而后续的Gnome默认不再支持X11。

软件包分裂的问题依旧存在，Ubuntu对snap软件包的坚持也是我放弃Ubuntu的一大原因。

总体而言，还是好的方面更多一些。

普通人是否能用Linux桌面系统？

很难直接回答Linux是否适合普通人使用，但是我建议是值得一试。Linux桌面系统并不是个怪物，也并不比Windows和MacOS更复杂。国内的Linux用户也不少，且不仅局限于IT从业者。遇到问题时上网也能查到很多资料。

当然，使用Linux时会有许多看起来复杂深奥的东西，但那些大部分是面向开发者的。因为Linux开放，所以这些让人如坠云雾的术语和底层知识会暴露给用户，但是这么多年来，我也没有了解多少细节，但依旧能用好这个系统。

对于普通用户来说，Linux桌面有软件中心、有扩展平台，几乎可以满足大部分的日常需求，甚至比Windows还简单。重要的是，Linux上没有流氓软件和定时炸弹般的弹窗，也没有盗版的烦恼。

对于国内用户来说，微信、腾讯视频会议、WPS、搜狗输入法、网易云音乐这些日常应用已经有Linux版本，而且有些比Windows上的体验更好。如果有兴趣，不如迈出那一步给自己一个机会。

总结

一个月以来，Debian 13的使用体验令人满意，这套软硬件组合预计还能再战数年。未来十年，Linux桌面仍将是我数字生活的重要组成部分。

我认识的许多研发工程师，甚至不知道Linux拥有成熟可用的桌面环境，仍以为它只是一个“黑乎乎的命令行”。看来，Linux桌面的普及之路，依旧任重而道远。

回首这十多年的历史，Linux和它的桌面系统一直在默默成长，变得越来越好。

SQLAlchemy中的联表查询

Sun, 31 Aug 2025 18:26:52 +0800

使用关系型数据库时，联表查询是一项常见的数据库操作。外键可以简化联表查询操作，确保数据的强约束和完整性。但对数据库管理而言，外键使得数据库的设计和维护变得复杂，降低灵活性。因此，许多公司禁止在业务中使用外键，而是在业务代码层保持数据的一致性。

Python中最流行的 SQLAlchemy 这个ORM库就能通过外键和自带的 relationship 函数实现跨表数据模型间的关系绑定。提供了基于外键，和基于join的2种方法。本文将从简到繁的一一介绍。

ORM 框架用于在关系型数据库和面向对象编程语言之间进行数据转换，允许开发者使用面向对象的方式来操作数据库，而不需要直接编写SQL语句，大大简化数据操作。

本来以常见的文章（post）数据库为例，比如数据库中有文章表（post）、文章分类表（category）和标签表（tag）。一般三者分属于3张表，但我们希望通过如下的方法直接访问文章的所属的分类和标签信息，就像文章表带了标签和分类字段一样。

期望的使用方法：

post.category   # 获取文章所属的分类
post.tags      # 获取文章的标签列表

本文将展示三种不同的方法实现以上需求：

使用基于类property的笨办法，底层用ORM的查询语句
使用外键，会增加数据库管理成本
使用join，既方便又直观

除了上面的单向查询，本文还有双向查询，即通过分类或者标签表的字段，反查与之相关联的文章列表。

以下代码的测试环境如下：

Python：3.12.7
SQLAlchemy：2.0.40

笨办法：基于property装饰器

为了避免使用外键，在很长一段时间里都在写下面这类代码实现联表查询。给数据模型定义一些property的方法，用于查询文章所属的分类。

class Category(Base):
    id = Column(Integer, primary_key=True)
    name = Column(String(50), nullable=False)

class Post(Base):
    id = Column(Integer, primary_key=True)
    title = Column(String(100), nullable=False)
    content = Column(String(1000))

    category_id = Column(Integer，nullable=False)

    @property
    def category(self):
        return Category.query.join(Category.id == self.category_id).all()

Post表和Category表通过Post表中的category_id字段关联起来。@property 装饰器使得可以用 Post.category查询文章的所属分类。

为此，只要引用其它表字段，都需要定义对应的property函数。接下来，再看看SQLAlchemy提供了什么有趣的方法。

基于外键的一对多双向查询方案

先从最简单的外键方案开始。设计一个简单场景，有文章表(posts)和分类表(categories)，分类和文章属于一对多关系：一篇文章仅属于一个分类，一个分类下有多篇文章。

业务需求是双向查询：

在文章模型中，可以通过category属性获得文章所属的分类
在分类模型中，可以通过 posts 属性获取分类下的所有文章

定义Category和Post两个模型类，将Post的category_id 列设置为外键。定义如下：

from sqlalchemy import ForeignKey, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship

class Base(DeclarativeBase):
    pass

class Category(Base):
    __tablename__ = "categories"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50), nullable=False)

    posts: Mapped[list["Post"]] = relationship(back_populates="category")

    def __repr__(self) -> str:
        return f"<Category(id={self.id}, name='{self.name}')>"

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    content: Mapped[str] = mapped_column(String(1000))

    category_id: Mapped[int] = mapped_column(ForeignKey("categories.id"))
    category: Mapped[Category] = relationship(Category, back_populates="posts")

Category 中定义了 posts 这个属性用于获取分类下的所有文章列表。posts 成员变量是用 relationship 创建的到 Post类的引用。由于 Post 对象此时未定义，所以写成字符串格式 "Post" 。
Post 中定义了 category_id 这个外键，关联到 categories.id 字段
Post 中也定义了category属性用于获取文章的分类，并使用 back_populates 做反向引用。

注意：relationship 函数反向引用的字段值 category 和 posts 是本对象（Category和Post）在目标对象（Post和Category）中属性名（category和posts）。

使用上面定义的模型，创建数据库、写入测试数据进行测试。

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine("sqlite:///blog.db")
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

# 添加2个分类
tech = Category(name="Technology")
life = Category(name="Life")
session.add_all([tech, life])
session.commit()

# 创建3篇文章
post1 = Post(title="Python ORM", content="SQLAlchemy tutorial", category_id=tech.id)
post2 = Post(title="Daily Life", content="My weekend", category_id=life.id)
post3 = Post(
    title="Advanced Python", content="Decorators explained", category_id=tech.id
)
session.add_all([post1, post2, post3])
session.commit()

# 通过文章获取分类
print(post1.category)
print("-" * 10)

# 通过分类获取所有文章
for post in tech.posts:
    print(post.title)

执行结果，符合预期

$ pip install sqlalchemy
$ python main1.py
<Category(id=1, name='Technology')>
----------
Python ORM
Advanced Python

查看sqlite中的表结构

$ sqlite3  blog.db
sqlite> .schema
CREATE TABLE categories (
    id INTEGER NOT NULL, 
    name VARCHAR(50) NOT NULL, 
    PRIMARY KEY (id)
);
CREATE TABLE posts (
    id INTEGER NOT NULL, 
    title VARCHAR(100) NOT NULL, 
    content VARCHAR(1000), 
    category_id INTEGER , 
    PRIMARY KEY (id), 
    FOREIGN KEY(category_id) REFERENCES categories (id)
);

看到 sqlite的posts 表中，category_id被定义成了外键，指向 categories 表的id字段。

上面整个模型的定义是比较简洁的，SQLAlchemy会利用外键，自动将两张表、两个数据模型关联起来，没有许多额外的设置。

基于ORM的双向关联查询

如果禁止了外键，开发者依旧希望使用简单方法获取数据实体对象间的关联信息。这就是基于join的方案。既然没有外键，就必须人为指定模型之间的关联方法，声明使用哪两列进行join操作。修改模型的定义如下：

...
class Category(Base):
    __tablename__ = "categories"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50), nullable=False)

    posts: Mapped[list["Post"]] = relationship(
        primaryjoin="Category.id == foreign(Post.category_id)",
        back_populates="category",
    )

    def __repr__(self) -> str:
        return f"<Category(id={self.id}, name='{self.name}')>"

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    content: Mapped[str] = mapped_column(String(1000))
    category_id: Mapped[int] = mapped_column()

    category: Mapped[Category] = relationship(
        primaryjoin="Post.category_id == Category.id",
        foreign_keys=[category_id],
        back_populates="posts",
    )

engine = create_engine("sqlite:///blog2.db")
...

在Category中的posts属性定义使用了 primaryjoin参数，显式指定两个模型的join规则。
Post.category_id 不再是外键
在 Category.posts 和 Post.category 两个字段中，都指定了join关系和反向引用。
在两个relationship函数中，前者使用了 "Category.id == foreign(Post.category_id)" 字符串, 后者使用了独立参数 foreign_keys=[category_id] 。二者的效果是一样的，这里故意用两种方法只是为了展示多种用法。foreign_keys参数的值也可以是字符串。

其它代码不用变，执行效果和使用外键一样，符合预期。

$ python main2.py 
<Category(id=1, name='Technology')>
----------
Python ORM
Advanced Python

检查表结构，注意 posts.category_id 不再是外键了

$ sqlite3 blog2.db 
sqlite> .schema 
CREATE TABLE categories (
    id INTEGER NOT NULL, 
    name VARCHAR(50) NOT NULL, 
    PRIMARY KEY (id)
);
CREATE TABLE posts (
    id INTEGER NOT NULL, 
    title VARCHAR(100) NOT NULL, 
    content VARCHAR(1000), 
    category_id INTEGER, 
    PRIMARY KEY (id)
);

数据库里没有外键，而是在ORM层实现了类似外键的效果，底层实际使用了join的方法将两个表关联起来。由于没有外键，所以更需要注意在业务代码中确保数据的一致性。

基于ORM的单向关系查询

之前是双向的查询，这里顺带也看看单向查询的例子，在这个例子中，单向查询的含义是，只能查询文章的分类，不能通过分类获取分类下的文章列表。

class Category(Base):
    __tablename__ = "categories"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50), nullable=False)

    def __repr__(self) -> str:
        return f"<Category(id={self.id}, name='{self.name}')>"

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    content: Mapped[str] = mapped_column(String(1000))
    category_id: Mapped[int] = mapped_column()

    category: Mapped[Category] = relationship(
        primaryjoin="foreign(Post.category_id) == Category.id",
    )

与之前代码的差别：

Category中，删除了 posts 属性
Post中，relationship 函数里，删除了 back_populates 参数，因为不需要反向映射了。

执行代码可以发现，post.category 依旧能获取到文章下的分类信息，但显然已经无法执行Category.post 了。

基于ORM的多对多关联表查询

除了上面分类和文章的一对多场景，常见的数据关系还有多对多关系，这里以文章和标签为例：一篇文章有多个标签，一个标签关联到多篇文章。这种场景一般会引入一张 relationships 的表，记录文章和标签的对应关系。模型定义如下：

class Relationship(Base):
    __tablename__ = "relationships"  # 新增relationships表

    tag_id: Mapped[int] = mapped_column(primary_key=True)
    post_id: Mapped[int] = mapped_column(primary_key=True)

class Tag(Base):
    __tablename__ = "tags"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(50), nullable=False)

    posts: Mapped[list["Post"]] = relationship(
        secondary="relationships",
        primaryjoin="Tag.id == Relationship.tag_id",
        secondaryjoin="Relationship.post_id == Post.id",
        back_populates="tags",
    )

    def __repr__(self):
        return f"<Tag(id={self.id}, name='{self.name}')>"


class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    content: Mapped[str] = mapped_column(String(1000))

    tags: Mapped[list[Tag]] = relationship(
        secondary="relationships",
        primaryjoin="Post.id == Relationship.post_id",
        secondaryjoin="Tag.id == Relationship.tag_id",
        back_populates="posts",
        uselist=True,
    )

这里 relationship 函数的参数多了一些：

定义了 relationships 表，表中post_id和tag_id两个字段分别是文章id和标签的id。
在 Tag 类的 posts 属性中，relationship 函数新引入了secondary 和 secondaryjoin 参数，用于把 relationships 表加入联表查询，实现3张表的联动。注意 secondary 的值必须是字符串格式的表名，而不能是映射的类名。
在 primaryjoin 和 secondaryjoin中共执行了两次join操作，将3张表关联起来。
Post类中，relationship的用法和Tag 中一样。

创建表和数据，验证效果。

engine = create_engine("sqlite:///blog4.db")
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

# 添加3个分类
python = Tag(name="Python")
linux = Tag(name="Linux")
devops = Tag(name="devops")
session.add_all([python, linux, devops])
session.commit()

# 创建3篇文章
post1 = Post(title="Python ORM", content="SQLAlchemy tutorial")
post2 = Post(title="Build Python", content="Build Python on linux")
post3 = Post(title="Drone CI", content="Deploy app with Drone on linux")
session.add_all([post1, post2, post3])
session.commit()

# 将文章和标签进行关联
session.add_all(
    [
        Relationship(post_id=post1.id, tag_id=python.id),
        Relationship(post_id=post2.id, tag_id=python.id),
        Relationship(post_id=post2.id, tag_id=linux.id),
        Relationship(post_id=post3.id, tag_id=devops.id),
        Relationship(post_id=post3.id, tag_id=linux.id),
    ]
)
session.commit()

# 获取文章的标签
print(post2.tags)
print("-" * 10)

# 通过标签获取所有文章
for post in linux.posts:
    print(post.title)

执行结果，成功获得文章包含的tag，以及打了对应tag的文章：

$ python main4.py
[<Tag(id=1, name='Python')>, <Tag(id=2, name='Linux')>]
----------
Build Python
Drone CI

查看表结构，也没有外键。

$ echo '.schema' | sqlite3 blog4.db
CREATE TABLE relationships (
    tag_id INTEGER NOT NULL, 
    post_id INTEGER NOT NULL, 
    PRIMARY KEY (tag_id, post_id)
);
CREATE TABLE tags (
    id INTEGER NOT NULL, 
    name VARCHAR(50) NOT NULL, 
    PRIMARY KEY (id)
);
CREATE TABLE posts (
    id INTEGER NOT NULL, 
    title VARCHAR(100) NOT NULL, 
    content VARCHAR(1000), 
    PRIMARY KEY (id)
);

数据库里的 relationships 表使用了联合主键。

总结

使用外键可以简化SQLAlchemy模型类的定义，方便代码中进行数据查询。
但外键也可能带来性能损失、增加运维管理复杂度，因此许多公司禁用了数据库外键。
通过SQLAlchemy 的relationship函数提供的方法，可以在ORM层定义模型关联方法。实现一对多和多对多的联表查询。
在使用SQLALchemy 提供的模型关联方法时，要注意在代码层确保数据的一致性。

EFK日志体系快速入门

Wed, 30 Jul 2025 19:43:08 +0800

7月，远方的风暴。

Elasticsearch、Filebeat、Kibana 合称EFK，常用于构建企业级的日志系统。Filebeat 在其中负责数据的采集：读取日志文件，将其发往Elasticsearch；Elasticsearch是数据库，处理和存储Filebeat发过来的数据；Kibana是UI，用于查询Elasticsearch中的数据。三者协作，构成了完整的日志平台。此外，Elasticsearch具有强大的全文搜索能力，也常在业务上用作搜索引擎。

本文将使用docker compose编排Nginx、Filebeat、Elasticsearch和Kibana，实现将Nginx的access log分字段解析后存储到Elasticsearch，并在Kibana上展示和查询。

演示环境：

Host：Debian 12
Docker版本：Docker 28.3.2

EFK各软件的版本在compose.yaml 中均有指定。不同版本Elasticsearch、Filebeat、Kibana的配置与界面很可能不一样，尽量使用新版本，如果和文章中的版本有出入导致无法成功配置，请看看官方文档。

$ mkdir /tmp/efk
$ cd /tmp/efk

Nginx配置文件

创建Nginx的目录，存放Nginx的配置文件和日志

$ mkdir -p nginx/logs

编辑Nginx的配置文件 nginx/nginx.conf，创建如下的精简化配置

user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;

events {
  worker_connections  1024;
}

http {
  include       /etc/nginx/mime.types;
  default_type  application/octet-stream;

  log_format main '[$time_local] | $http_host | $remote_addr | "$remote_user" | ' 
    '$request | $status | $body_bytes_sent | "$http_user_agent" | ' 
    '"$http_referer" | "$http_x_forwarded_for" | $request_time'; 


  access_log  /var/log/nginx/access.log  main;
  sendfile        on;
  keepalive_timeout  65;

  server {
    listen 80 default_server;
    server_name _;
    location / {
      root   /usr/share/nginx/html;
      index  index.html index.htm;
    }
  }
}

在文件中添加了server段配置。此外，修改了 Nginx的access log的格式，使用竖线分割日志各字段，可读性更高，也更方便使用工具分析。后续在Elasticsearch中，将使用pipeline对Nginx日志进行解析。

Filebeat配置

和Filebeat具备相同采集能力的还有Logstash、Fluentd等，选择Filebeat的原因是因为它用Golang编写，足够轻量，占用的资源少，适合在每个节点上作为守护进程部署。

创建Filebeat的配置文件目录

$ mkdir -p filebeat/data
$ sudo chown -R 1000:1000 filebeat

创建fileabeat的配置文件，filebeat/filebeat.yml，内容如下

filebeat.inputs:
  - type: filestream
    id: nginx_access_log_id
    prospector.scanner.fingerprint.length: 64
    paths:
      - /tmp/logs/access.log
    fields:
      log_type: nginx_access_log
    pipeline: "nginx_access_log_pipeline"


  - type: filestream
    id: nginx_error_log_id
    prospector.scanner.fingerprint.length: 64
    paths:
      - /tmp/logs/error.log
    fields:
      log_type: nginx_error_log

output.elasticsearch:
  hosts: ['elasticsearch:9200']
  flush_interval: 1s

  indices:
    - index: 'nginx_access_log-%{+yyyy_MM_dd}'
      when.equals:
        fields.log_type: "nginx_access_log"

    - index: 'nginx_error_log-%{+yyyy_MM_dd}'
      when.equals:
        fields.log_type: "nginx_error_log"

文件中定义了2个input，分别读取Nginx的access.log 和 error.log日志文件，并发往Elasticsearch中对应的index。

Elasticsearch的index的名字中使用了变量%{+yyyy_MM_dd}，用于区分index的日期，便于后续按日期删除久远的index。
对access log的index配置了pipeline。这个pipeline是用于解析Nginx的access log的。之后会手动在Elasticsearch中创建这个pipeline。

Filebeat的配置建议参考：https://www.elastic.co/docs/reference/beats/filebeat/filebeat-reference-yml

Filebeat除了可以将日志输出到Elasticsearch外，支持的output插件的还有Kafka和Logstash等等。使用Kafka（Filebeat -> Kafka -> Elasticsearch）的好处是可以做到流量削峰，应对瞬时大流量；使用Logstash（Filebeat -> Logstash -> Elasticsearch）的好处是可以利用Logstash丰富的日志解析处理能力；当然，也能将二者进一步结合，形成Filebeat -> Kafka -> Logstash -> Elasticsearch 的处理链路。不论经历了多少轮中间件的处理，日志的最终归宿一般还是Elasticsearch。

docker compose 部署

创建Elasticsearch的数据目录

$ mkdir es_data
$ sudo chown -R 1000:1000 es_data

创建compose.yaml文件，编排所有的容器，内容如下：

services:
  nginx:
    image: nginx:1.29.0
    volumes:
      - ./nginx/logs/:/var/log/nginx/         # 日志输出到宿主机目录
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
    ports:
      - 80:80

  filebeat:
    image: elastic/filebeat:9.1.0
    container_name: filebeat
    restart: always
    volumes:
      - ./filebeat/filebeat.yml:/usr/share/filebeat/filebeat.yml
      - ./filebeat/data:/usr/share/filebeat/data
      - ./nginx/logs:/tmp/logs:ro   # 挂载宿主机上的日志目录到容器内

  elasticsearch:
    image: elasticsearch:9.0.4
    container_name: elasticsearch
    restart: always
    environment:
      - cluster.name=elasticsearch
      - "ES_JAVA_OPTS=-Xms1g -Xmx1g"
      - discovery.type=single-node
      - xpack.security.enabled=false
      - xpack.security.enrollment.enabled=false
    ports:
      - "9200:9200"
      - "9300:9300"
    volumes:
      - ./es_data:/usr/share/elasticsearch/data
    healthcheck:
      interval: 5s
      retries: 60
      test: curl --fail -s -o /dev/null http://127.0.0.1:9200/

  kibana:
    image: kibana:9.0.4
    container_name: kibana
    restart: always
    environment:
      - ELASTICSEARCH_URL=http://elasticsearch:9200
    ports:
      - "5601:5601"
    depends_on:
      elasticsearch:
        condition: service_healthy

配置说明：

nginx：把nginx/nginx.conf 映射到容器内，把Nginx容器里的日志目录映射到宿主机上。
filebeat：把Nginx的日志以只读方式映射到Filebeat容器内，方便Filebeat读取和采集。
elasticsearch：将Elasticsearch的数据保存目录映射到外部做数据持久化。
kibana：配置Elasticsearch的地址配置到环境变量中，启动的时候会依赖Elasticsearch。

本文这里使用了单节点的Elasticsearch。如果想了解在Docker中对Elasticsearch做集群化部署的方案，请查看官方文档：https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-elasticsearch-docker-compose

安全声明：本文简化了部署的配置，关闭了Elasticsearch的认证等功能，在生产中部署时，还是需要启用这些安全选项。

启动compose

$ docker compose up -d

检查Elasticsearch的状态

$ curl http://127.0.0.1:9200/_cat/health?v
epoch      timestamp cluster       status node.total node.data shards pri relo init unassign unassign.pri pending_tasks max_task_wait_time active_shards_percent
1753751269 01:07:49  elasticsearch yellow          1         1     37  37    0    0        5            0             0                  -                 88.1%

正常的Elasticsearch集群状态应该是green，由于这里是单节点Elasticsearch，所以状态是yellow，但不影响后面的操作。

Elasticsearch配置pipeline

Elasticsearch中pipeline可以对消息执行解析、拆分、转化、增删等操作。详细可以查看文档： https://www.elastic.co/docs/reference/enrich-processor/

创建如下的json文件，命名为 nginx_access_log_pipeline.json，内容是用于解析Nginx的access log的pipepine。其中的grok处理器提供了从字符串字段中提取并结构化字段的模式，为各个字段指定名字，设置类型。

{
  "description": "Nginx access log pipeline",
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": [
          "\\[%{HTTPDATE:timestamp}\\] \\| %{DATA:domain} \\| %{IP:client_ip} \\| \"%{DATA:remote_user}\" \\| %{WORD:method} %{DATA:request} %{DATA:http_version} \\| %{NUMBER:status_code:int} \\| %{NUMBER:response_size:int} \\| \"%{DATA:user_agent}\" \\| \"%{DATA:referer}\" \\| \"%{DATA:x_forwarded_for}\" \\| %{NUMBER:response_time:float}"
        ],
        "ignore_missing": true
      }
    },
    {
      "date": {
        "field": "timestamp",
        "target_field": "@timestamp",
        "formats": [
          "dd/MMM/yyyy:HH:mm:ss Z"
        ]
      }
    },
    {
      "remove": {
        "field": [
          "timestamp",
          "ecs.version"
        ]
      }
    }
  ]
}

通过Elasticsearch接口创建pipeline

$ curl -X PUT -H "content-type: application/json" \
    http://127.0.0.1:9200/_ingest/pipeline/nginx_access_log_pipeline \
    -d @./nginx_access_log_pipeline.json

检查创建好的pipeline

# 查看所有pipline
$ curl http://127.0.0.1:9200/_ingest/pipeline | jq .

# 或者，查看具体的pipeline
$ curl http://127.0.0.1:9200/_ingest/pipeline/nginx_access_log_pipeline?pretty

pipeline相关api的文档：https://www.elastic.co/guide/en/elasticsearch/reference/master/get-pipeline-api.html

测试日志采集

启动docker compose后，访问Nginx会产生日志，并被Filebeat采集和发往Elasticsearch中。

$ curl http://127.0.0.1/    # status_code 200
$ curl http://127.0.0.1/x   # status_code 404

查看Elasticsearch中的日志数量

$ curl -s http://127.0.0.1:9200/_cat/indices?v | awk '/nginx/ || NR ==1'
health status index                          uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   nginx_access_log-2025_07_30    L4T0gXEJQjiOIIvOX3oBhw   1   1          2            0       227b           227b         227b
yellow open   nginx_error_log-2025_07_30     88e58AUhQ3SW2_zRNWPj7w   1   1         19            0     36.7kb         36.7kb       36.7kb

这里可以看到Nginx的access log和error log的条目数量和占用的空间大小。

配置Kibana查询

在浏览器中打开Kibana的地址: http://127.0.0.1:5601 。通过如下的方法，创建Kibana的数据视图，并在Kibana中执行各式各样的查询方法。

创建Kibana的Data View

1 ）打开Kibana的左侧边栏，点击Management，然后继续在左侧边栏的Kibana下点击Data Views 。或者直接打开 http://127.0.0.1:5601/app/management/kibana/dataViews 。
2）在新页面中点击Create data view这个按钮。在弹出的表单中填写数据视图。
- Name：nginx_access_log
- Index pattern：nginx_access_log-*
- 填写好之后，点击 Save data view to Kibana 按钮提交。
3）用和上面同样的方法为Nginx的error log创建 nginx_error_log的Data view。

在Kibana中查询日志

1）打开左侧栏，在 Analytics 下点击 Discover ，或者直接打开链接 http://127.0.0.1:5601/app/discover#/ 。
2）在页面左上角的 Data view中选中刚刚创建的 nginx_access_log，就可以看到刚刚生成的access log了，有2条访问记录。
- 在左侧可以看到日志的拆分后的所有字段
- 在搜索框中输入 status_code: 404 查看http返回码为 404的日志。
3）Kibana上切换Data view到nginx_error_log
- 查看界面左侧的日志字段，由于没有用pipeline做字段解析，大部分都是内置字段
- 在搜索框中输入 "no such file"，使用模糊搜索的方式查询日志，可以查到对应的错误日志。

Elasticsearch的常用API

Elasticsearch 的API接口操作方法见链接，https://www.elastic.co/docs/api/doc/elasticsearch/v9/

检查集群的基本信息，包括各组组件版本，兼容性。

$ curl http://127.0.0.1:9200/

查看集群的健康状态

$ curl http://127.0.0.1:9200/_cluster/health?pretty

查看Elasticsearch集群的节点信息

$ curl -s http://127.0.0.1:9200/_cat/nodes?v

index的操作

创建index

$ curl -X PUT -H "content-type: application/json" http://127.0.0.1:9200/test-00001 -d '{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}'

查看index的设置

$ curl http://127.0.0.1:9200/test-00001/_settings?pretty

查看所有index

$ curl http://127.0.0.1:9200/_cat/indices

查看具体index的信息，包括分片、副本等详细信息

$ curl http://127.0.0.1:9200/test-00001

向index批量写入数据，如果指定的index不存在，会自动创建

$ curl -X POST http://127.0.0.1:9200/_bulk?pretty \
  -H "Content-Type: application/json" \
  -d'{ "index" : { "_index" : "test-00001" } }
    {"name": "kong", "age": "bar" }
    { "index" : { "_index" : "test-00001" } }
    {"name": "ming", "title": "bar" }
    { "index" : { "_index" : "test-00001" } }
    {"name": "fang", "title": "bar" }
'

查看index的mapping，mapping相当于关系数据库中的schema，用于定义索引的结构和字段类型等。

$ curl http://127.0.0.1:9200/nginx_error_log-2025_07_30/_mapping

删除index

$ curl -X DELETE http://127.0.0.1:9200/test-00001

搜索操作

Elasticsearch的详细查询用法，参考：https://www.elastic.co/docs/reference/query-languages/querydsl ，下面介绍常用的两种。

查看access log 索引中的status_code=404的条目。

$ curl -H "content-type: application/json" http://127.0.0.1:9200/nginx_access_log-2025_07_30/_search -d  '
{"query":{"match": {"status_code": 404}}}'

对error log 进行模糊搜索，查找 "not found" 字符串。

$ curl -H "content-type: application/json" http://127.0.0.1:9200/nginx_error_log-2025_07_30/_search -d  '
{"query":{"query_string": {"query":"No such file"}}}'

总结

本文概述了EFK日志管理系统的核心概念和组件，使用docker compose 搭建了一个简易版本的EFK系统。如果要将其用于生产环境，各个组件都还有很大的优化空间，尤其是在Elasticsearch的集群部署和安全认证方面还有很多工作要做。

需要指出的是，EFK体系作为一个强大而复杂的日志管理解决方案，其功能远不止本文所涉及的入门知识，Filebeat、Elasticsearch、Kibana的配置项都十分丰富，本文仅仅浅尝了其中的百分之一。当遇到问题时，建议读读文中提到的官方文档。最后，期望你玩的愉快。

使用ollama搭建开源AI编程助手

Sun, 15 Jun 2025 13:52:58 +0800

水中投影，似真似幻

当前，大公司大模型几乎主导了AI行业。作为个人，把所有的数据和隐私全部上交，固然能获得很好的智能体验。不过，开源生态也一如既往的提供了一些丰富的选择，对许多个人和企业来说，用开源工具私有化部署开源模型不失为一种可行的方案。

这篇文章会基于开源的LLM模型（Qwen、Ollama、deepseek等）、开源的模型工具（Ollama）、开源的插件集成（VSCode+Continue插件）方案，搭建一个基础的编程编程助手。重点在于Ollama这个模型工具的用法。

Ollama 是一个开源的大型语言模型（LLM）工具，专注于在本地运行和管理各种 AI 模型。支持许多流行的模型，比如 deepseek-r1、gemma3、qwen3、llama4等。Ollama大大简化了用户下载和运行模型的过程。

同时，Ollama还获得了许多流行的集成工具的支持，比如Open WebUI、dify等等，许多开源工具都可以使用Ollama的接口。

环境

RockyLinux 9
Ollama 0.9.0

安装Ollama

Ollama的项目地址：https://github.com/ollama/ollama 官方网站：https://ollama.com/

这里使用二进制解压部署的方式。从Ollama官方下载压缩包，解压之后就可以直接使用了。

$ mkdir ollama
$ cd ollama
$ wget https://ollama.com/download/ollama-linux-amd64.tgz
$ tar xvf ollama-linux-amd64.tgz
$ export PATH=$PATH:$PWD/bin   # 将ollama命令加入PATH环境变量中

官方也提供了其它安装方式。参考：https://ollama.com/download

安装好之后，使用ollama --version 查看Ollama的版本。

$ ollama --version
ollama version is 0.9.0

输出版本号就代表安装好了。

下载和运行模型

Ollama的命令比较简单，可以通过 ollama --help 查看所有的子命令。下面先介绍基础的模型管理命令。

模型的管理

Ollama的server端和client端都是同一个二进制文件 ollama。要运行客户端命令，先要启动Ollama的服务端。

运行服务端

ollama serve 运行Ollama服务端，测试中我们将其放置在前台运行，方便观察。

$ ollama serve

Ollama 的server端运行在 11434 端口上。几乎所有的Ollama命令都是通过HTTP协议和Ollama服务端的交互。

下载模块

新开一个终端，运行ollama pull <model name>的命令。这里尝试下载 deepseek-r1:1.5b 和 qwen3:4b 模型。

新开窗口运行ollama命令的话，也需要执行 export PATH=$PATH:$PWD/bin 添加环境变量，否则就要写全ollama可执行文件的路径。

$ ollama pull deepseek-r1:1.5b
$ ollama pull qwen3:4b

Ollama官网有列出了所有可以直接下载使用的模型（可以使用 ollama pull 下载的）列表：https://ollama.com/library 。大部分时候，模型下载速度还可以。

ollama list查看下载的模型

$ ollama list
NAME                                     ID              SIZE      MODIFIED     
deepseek-r1:1.5b                         a42b25d8c10a    1.1 GB    4 weeks ago     
qwen3:4b                                 a383baf4993b    2.6 GB    6 weeks ago

模型详情

ollama show <model name>查看模型的详情，显示模型的参数量，上下文长度、量化信息等。

$ ollama show deepseek-r1:1.5b
  Model
    architecture        qwen2     
    parameters          1.8B      
    context length      131072    
    embedding length    1536      
    quantization        Q4_K_M    

  Capabilities
    completion    

  Parameters
    stop    "<｜begin▁of▁sentence｜>"    
    stop    "<｜end▁of▁sentence｜>"      
    stop    "<｜User｜>"                 
    stop    "<｜Assistant｜>"            

  License
    MIT License                    
    Copyright (c) 2023 DeepSeek

删除模型

ollama rm <model name> 删除模型。删除后，模型会从文件系统中删掉。

$ ollama rm qwen3:4b 
deleted 'qwen3:4b '

运行模型

上面的命令都是对静态模型文件的增删和查看。下面看看如何运行和停止模型、与模型对话。

运行模型

ollama run <model name>运行 deepseek-r1:1.5b 模型。如果指定运行的模型不存在，Ollama会尝试从官方仓库下载。

$ ollama run deepseek-r1:1.5b
>>> hi
<think>

</think>

Hello! How can I assist you today? 😊

>>> Send a message (/? for help)

执行run命令后，Ollama提供了一个命令行的交互式对话界面，用于和模型进行对话。

查看运行中的模型

再新开一个终端，使用ollama ps 查看运行中的模型。

$ ollama ps
NAME                ID              SIZE      PROCESSOR    UNTIL            
deepseek-r1:1.5b    a42b25d8c10a    3.3 GB    100% CPU     4 minutes from now

从命令的输出结果中看到，由于本机没有显卡，模型完全使用了CPU运行。

停止模型运行

ollama stop <model name>停止运行中的模型

$ ollama stop deepseek-r1:1.5b

以上就是ollama命令的基础用法。

HTTP访问Ollama

以上都是通过ollama命令和Ollama server交互，之前说过Ollama客户端和server之间是通过HTTP协议通信。所以，也不是非得用ollama命令，通用的HTTP client也能向Ollama的server端发起请求，也能完成上面的任务。比如，查看运行中的模型

$ curl -s 127.0.0.1:11434/api/ps | jq .
{
  "models": [
    {
      "name": "deepseek-r1:1.5b",
      "model": "deepseek-r1:1.5b",
      "size": 1567668736,
      "digest": "a42b25d8c10a841bd24724309898ae851466696a7d7f3a0a408b895538ccbc96",
      "details": {
        "parent_model": "",
        "format": "gguf",
        "family": "qwen2",
        "families": [
          "qwen2"
        ],
        "parameter_size": "1.8B",
        "quantization_level": "Q4_K_M"
      },
      "expires_at": "2025-06-12T18:17:00.179778313-04:00",
      "size_vram": 0
    }
  ]
}

发起chat请求

curl --request POST \
  --url http://127.0.0.1:11434/api/generate \
  --header 'content-type: application/json' \
  --data '{
  "model": "qwen3:4b",
  "prompt": "讲个笑话",
  "format": "json"
}'

环境变量

ollama命令行的参数很少，主要是通过环境变量控制server和client端的行为。

ollama server端环境变量

可以通过环境变量控制Ollama server的行为，详细环境变量查看：https://github.com/ollama/ollama/blob/main/envconfig/config.go#L239

下面是几个常用的server端环境变量：

OLLAMA_MODELS：设置Ollama中本环境变量指定的目录加载模型
OLLAMA_KEEP_ALIVE：模型在内存中的生存时间，到期之后会被stop，默认是5分钟
OLLAMA_HOST：模型的监听IP地址，默认127.0.0.1，要对其它机器暴露的话，可以设置为 0.0.0.0
OLLAMA_DEBUG：开启模型的DEBUG
HTTP_PROXY：为Ollama设置HTTP代理
OLLAMA_NUM_PARALLEL：客户端的请求并发数

对于临时部署，比较喜欢下面这种方式使用环境变量

$ OLLAMA_KEEP_ALIVE=480m OLLAMA_HOST=0.0.0.0 ollama serve

到达 OLLAMA_KEEP_ALIVE指定的时间后，模型会停止运行，再对模型发起请求的时候会触发Ollama重新加载模型，这个加载速度比较慢，因此建议调高 OLLAMA_KEEP_ALIVE这个环境变量。

默认Ollama运行在 127.0.0.1上，为了让其它节点访问，OLLAMA_HOST可以修改为 0.0.0.0 。

Ollama没有认证机制，因此暴露给其它机器的时候要格外小心，可以结合网络防火墙、封装一层HTTP反向代理添加认证进行加固。千万不要直接暴露Ollama端口到外网环境。

Ollama 客户端环境变量

Ollama的客户端主要的环境变量也是 OLLAMA_HOST，但是和server上的用途不同，客户端使用这个环境变量可以让 ollama客户端连接该变量指向的Ollama server，这个变量默认是本地Ollama server，也即 http://127.0.0.1:11434。

AI代码助手

接下来，结合VSCode和 continue 插件，在VSCode中调用Ollama部署的模型，实现一个基础的AI代码助手。

continue是专注于AI编程的IDE插件，支持VSCode 和JetBrains ，特点是可以方便的使用自己想要使用的模型。continue默认支持配置OpenAI、Deepseek、Gemini等大模型，也能支持Ollama、llama.cpp等开源工具部署的模型。灵活性很高，用户不必绑死在一个厂家上。可以作为github copilot的一个替代方案。

vscode和continue插件配置

不同版本的continue插件配置方法可能不一样，旧版本continue用的是json配置文件，现在改为了yaml。Continue的配置项参考：https://docs.continue.dev/reference ，提供了很丰富的配置样例。下面是基于Ollama的配置方法。

首先为VSCode安装continue插件，完成后，在VSCode的左侧栏多了一个Continue的图标。
点击Continue图标，左侧出现Continue的对话界面，点击对话框下方的Select model -> Add Chat Model，弹出了添加模型的界面。窗口中添加的Ollama只能使用本地部署的Ollama，也即127.0.0.1，如果要使用远程的Ollama，需要编辑配置文件。
点击界面最下方的 config file 链接，进入Continue配置文件。配置文件路径实际是 ~/.continue/config.yaml ，也可以直接编辑。

在打开的Continue配置文件的models配置块中添加如下的配置项：

...
models:
  - name: qwen2.5-coder
    model: "qwen2.5-coder:1.5b-base"
    provider: ollama
    apiBase: "http://192.168.1.10:11434"
    roles: 
      - autocomplete
    defaultCompletionOptions:
      temperature: 0.7

  - name: deepseek-r1
    model: "deepseek-r1:1.5b"
    provider: ollama
    apiBase: "http://192.168.1.10:11434"
    roles: 
      - chat
...

上面的配置中添加了两个模型，一个用于代码补齐（autocomplete），一个用于聊天（chat）。然后就可进行AI辅助编程了。

因为希望代码补全能快一点，因此对autocomplete的实时要求比较高，由于没有显卡，这里使用参数量较小的 qwen2.5-coder:1.5b-base ，速度快，但理解能力也就差一些。

做完上面的配置，返回到vscode的编程窗口，打开一个代码文件，现在可以测试补全功能了。

制作模型文件

如果Ollama的模型库中没有提供想要使用的模型怎么办？

常见的模型文件有 Safetensors 和 GGUF两种格式，前者是 Hugging Face开发的，安全系数高。而GGUF是专为量化模型设计的，将模型架构、权重和超参数整合为单一文件，简化部署，主要用于本地推理。

Ollama 默认支持gguf格式的模型，而Safetensors需要进行转换成gguf后，才能被Ollama使用。

加载gguf格式模型

如果Ollama官方没有提供想要的模型，可以到 https://huggingface.co/ 搜索gguf格式的模型。比如qwen1_5-7b-chat-q5_k_m.gguf 。

较小的模型只有一个 gguf 文件，可以先下载到本地，再创建文件Modelfile，内容如下

FROM qwen1_5-7b-chat-q5_k_m.gguf

启动Ollama的服务端后，加载模型，名字自定义为 qwen1_5-7b

$ ollama create qwen1_5-7b -f Modelfile

查看加载的模型

$ ollama list
NAME                ID              SIZE      MODIFIED     
qwen1_5-7b:latest    fd36fede3ee1    5.5 GB    7 seconds ago
...

之后就可以运行模型和对话了。

如果是较大的模型，可能有多个 gguf文件，这个时候就要进行合并了。

gguf文件合并

如果模型较大，可能有多个gguf，Ollama使用的时候，需要合并为一个gguf文件。llama.cpp 项目提供了合并的功能。建议使用llama.cpp项目的docker镜像来进行模型的合并。

下载模型拆分后的各个部分，拆分后的文件格式是带编号的，比如下面的这些文件，文件名字中指定了每个文件在整个模型中的顺序。

$ ls -lh qwen2.5-coder-7b-instruct-fp16-0000*
-rw-r--r-- 1 root root 3.7G 9月  20 2024 qwen2.5-coder-7b-instruct-fp16-00001-of-00004.gguf
-rw-r--r-- 1 root root 3.6G 9月  20 2024 qwen2.5-coder-7b-instruct-fp16-00002-of-00004.gguf
-rw-r--r-- 1 root root 3.6G 9月  20 2024 qwen2.5-coder-7b-instruct-fp16-00003-of-00004.gguf
-rw-r--r-- 1 root root 3.4G 9月  20 2024 qwen2.5-coder-7b-instruct-fp16-00004-of-00004.gguf

接下来，将存放模型文件的本地目录映射到容器的/tmp/gguf 目录下，启动容器

$ docker run -it -v ./:/tmp/gguf \
    --entrypoint /bin/bash \
    --rm ghcr.io/ggerganov/llama.cpp:full

进入容器后，检查文件没问题后执行模型合并操作，将上面4个分片合并成一个gguf文件：

$ ls /tmp/gguf
qwen2.5-coder-7b-instruct-fp16-00001-of-00004.gguf
qwen2.5-coder-7b-instruct-fp16-00002-of-00004.gguf
qwen2.5-coder-7b-instruct-fp16-00003-of-00004.gguf
qwen2.5-coder-7b-instruct-fp16-00004-of-00004.gguf

$ pwd
/app 

$ ./llama-gguf-split --merge /tmp/gguf/qwen2.5-coder-7b-instruct-fp16-00001-of-00004.gguf /tmp/gguf/qwen2.5-coder-7b-instruct-fp16.gguf   # 合并

$ ls -lh /tmp/gguf
total 29G
-rw-r--r-- 1 root root 3.7G Sep 20  2024 qwen2.5-coder-7b-instruct-fp16-00001-of-00004.gguf
-rw-r--r-- 1 root root 3.6G Sep 20  2024 qwen2.5-coder-7b-instruct-fp16-00002-of-00004.gguf
-rw-r--r-- 1 root root 3.6G Sep 20  2024 qwen2.5-coder-7b-instruct-fp16-00003-of-00004.gguf
-rw-r--r-- 1 root root 3.4G Sep 20  2024 qwen2.5-coder-7b-instruct-fp16-00004-of-00004.gguf
-rw-r--r-- 1 root root  15G Jun 12 15:20 qwen2.5-coder-7b-instruct-fp16.gguf

注意：

在存放模型碎片的 /tmp/gguf 目录下，最好不要有任何多余的文件，否则可能会执行失败
要在 /app 目录下执行 llama-gguf-split命令，否则会找不到依赖的库文件
合并的gguf文件时，只需要指定分片中的第一个文件路径
最后一个参数是要输出的gguf的文件名字

生成的文件差不多是原来各分片文件的大小之和。

退出llama.cpp容器，编写Modelfile 加载合并之后的模型

FROM qwen2.5-coder-7b-instruct-fp16.gguf

用Ollama创建模型

$ ollama create qwen2.5-coder-7b-instruct -f models/Modelfile 
$ ollama ls
NAME                                          ID              SIZE      MODIFIED       
qwen2.5-coder-7b-instruct:latest              abf09b5f0c56    15 GB     33 seconds ago

Safetensors 格式的模型

safetensors格式的模型需要adapter才能支持，没试过，可以参考官方文档。

https://github.com/ollama/ollama/blob/main/docs/import.md

总结

Ollama作为开源的大语言模型本地化部署工具，为开发者提供了简单高效的解决方案。它支持主流开源模型的快速部署与管理，无需GPU即可在纯CPU环境下运行，既保障了数据隐私安全，又降低了使用门槛。通过命令行工具可实现模型的下载、运行和监控，并支持自定义模型加载。无论是隐私敏感场景的应用开发，还是本地AI方案的快速验证，Ollama都能提供灵活可靠的支撑。

但是，Ollama也有非常严重的短板，那就是只支持单机部署和推理，无法集群化、规模化使用。不过，Ollama依旧是模型运行和验证领域的绝佳工具。即使我没有显卡，只有一台128G内存和24核CPU的老服务器，也能拿一些小参数的模型做做试验。

个人以为，当下的大模型正如半个世纪以前的计算机，体格巨大，性能缓慢。随着技术发展，未来大模型也会和手机、电脑一样，性能更强、体积更小，走进千家万户。

Linux内核模块编写和调试

Sat, 24 May 2025 16:24:41 +0800

黄昏时分

接上一篇文章的内容编译和运行新版本Linux内核，本文中，我们继续学习内核模块相关的基础知识。为了方便以后为Linux内核贡献代码，这次看看如何编写一个简单的内核模块，以及将其集成到Linux内核代码中，并使用GDB调试内核和我们写的内核模块。

这篇文章紧接上文，因此会简化上文已经详细介绍的内核编译、QEMU等基础知识，如果过程中卡壳了，建议从上文编译和运行新版本Linux内核中寻找答案试试。也可以在评论区留言。

一个简单的内核模块

Linux内核模块是一种动态可加载的内核对象（LKM, Loadable Kernel Module），用于在运行时扩展内核功能而无需重新编译或重启系统。这种模块化机制实现了核心内核与功能组件的解耦，使得文件系统、网络协议栈、设备驱动程序以及各类硬件支持能够以独立模块的形式存在。如果不模块化，而是将这些功能全部集成到内核中，不仅会导致内核过于庞大，还会有许多不需要的功能被默认加载。此外，每次功能变动都需要安装最新内核，并且必须重启系统。因此，动态加载的内核模块是Linux内核保持轻量和灵活的重要原因。

内核模块通常使用C语言编写，本文中只需要编写一个简单的“Hello Word”演示程序，用于了解如何编写和使用内核模块。不会有太多的知识门槛。

编写内核模块

创建hello_module目录，编写如下的模块代码 hello.c：

#include <linux/init.h>
#include <linux/module.h>
#include <linux/kernel.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Xnow");
MODULE_DESCRIPTION("A simple Linux kernel module.");
MODULE_VERSION("0.1");

static char message[] = "Hello, World!";

static int __init hello_init(void) {
    printk(KERN_INFO "********** %s **********\n", message);
    return 0;
}

static void __exit hello_exit(void) {
    printk(KERN_INFO "Goodbye, World!\n");
}

module_init(hello_init);
module_exit(hello_exit);

这个和我们日常写的hello world还是挺不一样的： + include 语句包含必要的头文件； + MODULE_ 行，明确这个模块的开源协议、作者、版本和描述等信息。 + staic char message[] 定义一个全局字符串message。 + hello_init() 和 hello_exit() 两个函数分别输出 message和“Goodbye, World!\n” 字符串。 + module_init 和module_exit 两个宏分别指定模块加载时的初始化函数和卸载时的清理函数。

在同一目录下继续创建 Makefile，内容如下：

注意，Makefile中的缩进是 tab，而不是空格

obj-m += hello.o

KDIR ?= /lib/modules/$(shell uname -r)/build

all:
    make -C $(KDIR) M=$(PWD) modules

clean:
    make -C $(KDIR) M=$(PWD) clean

obj-m += hello.o：指定将hello.c 文件编译成hello.ko模块文件。
KDIR：指向当前系统的内核源码目录（通常是 /lib/modules/$(uname -r)/build）。
make -C $(KDIR) M=$(PWD) modules ：
- -C $(KDIR): 切换到内核源码目录 $(KDIR)，在该目录下执行 make。
- M=$(PWD): 指定模块源码的目录为当前目录 $(PWD)。$(PWD) 是一个环境变量，表示当前工作目录。
- modules: 表示要编译模块。

这里$(KDIR) 指向当前运行中内核的源码目录。有时候，软件仓库里并没有提供当前运行内核开发包，可能是运行的内核版本已经过时了。这时，也可以安装略有版本差异的内核开发包试试，在 Makefile文件为KDIR指定具体的内核开发包版本的路径即可。

比如我运行的内核是 5.14.0-503.14.1.el9_5.x86_64，但是仓库里只能安装 5.14.0-503.40.1.el9_5.x86_64。这时，可以安装kernel-devel-5.14.0-503.40.1.el9_5.x86_64 和 kernel-core-5.14.0-503.40.1.el9_5.x86_64这2个包。然后修改 KDIR，修改为 KDIR ?= /lib/modules/5.14.0-503.40.1.el9_5.x86_64/build 这个版本路径，也是一样能编译和加载的。

这里涉及到了vermagic 变量和兼容性等问题，不做过多展开。实际上面举例的两个包是同一个版本的内核（5.14.0），只是补丁版本不一致。

编译和测试内核模块

先安装内核的开发包，之后执行编译和加载

$ sudo yum -y install make kernel-devel-$(uname -r) kernel-core-$(uname -r)
$ make   # 编译
$ ls     # 检查编译结果
hello.c  hello.ko  hello.mod  hello.mod.c  hello.mod.o  hello.o  Makefile  modules.order  Module.symvers

$ file hello.ko 
hello.ko: ELF 64-bit LSB relocatable, x86-64, version 1 (SYSV), BuildID[sha1]=4ffdbb56e4c75c31b728d4fc1b07dc65c51159d8, with debug_info, not stripped

编译完成后，生成了模块文件和各类临时文件， hello.ko 是需要的内核模块文件，也可以使用modinfo 查看内核模块的信息。

$ modinfo ./hello.ko 
filename:       ./hello.ko
version:        0.1
description:    A simple Linux kernel module.
author:         Xnow
license:        GPL
rhelversion:    9.5
srcversion:     EE1A7DC8C21A87AB57A923B
depends:        
retpoline:      Y
name:           hello
vermagic:       5.14.0-503.40.1.el9_5.x86_64 SMP preempt mod_unload modversions

接下来试试加载和卸载模块

$ sudo insmod hello.ko  # 加载模块
$ sudo dmesg  | tail -1 
[xxxxxx] ********** Hello, World! **********

$ sudo lsmod  | grep -i hello   # 查看
hello                  16384  0

$ sudo rmmod hello  # 卸载模块
$ sudo dmesg  | tail -1 
[xxxxxx] Goodbye, World!

insmod 用于加载内核模块
模块代码中的 printk() 函数会将内容输出到 dmesg 内核日志文件中
lsmod 和 cat /proc/modules 命令可以看到已经加载的模块
rmmod 用于卸载模块，卸载时的函数也执行了。

模块集成到内核并编译

将模块集成到内核代码中

上面的步骤是动态的编译和加载内核模块。但是如何将模块内置到Linux源码中，并使用gdb对内核代码进行调试呢？

创建 debug_linux 目录，这个目录将作为我们调试内核的主要目录。在目录下下载最新的Linux 的内核源码，解压。之后把上面的 hello.c 文件放到内核源码中的 drivers 目录下。

$ wget https://mirrors.aliyun.com/linux-kernel/v6.x/linux-6.14.6.tar.xz
$ tar xvf linux-6.14.6.tar.xz
$ cd linux-6.14.6
$ cp ../../hello_module/hello.c drivers/

修改 drivers/Kconfig，在menu行的后面添加如下行

config HELLO
    tristate "Hello World Module"

tristate表示这个配置选项为三态选项，即编译内核时对该模块有三种选择： + <*>，即y：编译并内置到内核中。 + <M>，编译为模块，可以在运行时加载。 + < >，即n，表示不编译，不包含在内核中。

除了 tristate，还有bool类型的选项，有两种状态 + [*]：通常用于非模块化选项，表示启用某个内核配置选项。 + [ ]：表示不启用

这几个选项类型在编译内核的make menuconfig阶段中会看得到。

继续修改 drivers/Makefile，在文件内容起始处添加如下行：

obj-$(CONFIG_HELLO)     = hello.o

CONFIG_HELLO 也就是对应上面Kconfig文件中配置的 config HELLO。

内核 drivers 目录的逻辑是十分严格的，所有模块都有各自的目录，各安其位，组织严密。我们直接将代码放到 drivers 目录的做法是临时测试的走捷径方法，实际中是不允许的。

编译内核：启用hello模块和调试选项

接下来又是熟悉的编译内核环节。

$ make mrproper  
$ make x86_64_defconfig   # 生成针对 x86_64架构的默认配置文件
$ make menuconfig

在make menuconfig 对Linux内核做如下定制。 + 禁用内核的地址随机化，方便后续的内核调试 + 关闭多媒体、声卡和虚拟化支持，加快编译速度 + 开启内核debug模式，用于调试内核 + 启用我们自己编写的Hello World模块

# 关闭地址随机化，不然断点处无法停止。
Processor type and features
 [] Randomize the address of the kernel image (KASLR)   # 取消勾选

[ ] Virtualization  ----

Device Drivers  --->
  <*> Hello World Module   # 编写的模块，启用
  < > Multimedia support  ----
  < > Sound card support  ---- 

# 启用内核debug
Kernel hacking
  [*] Kernel debugging
  Compile-time checks and compiler options
    Debug information (Rely on the toolchain's implicit default DWARF version)  --->  # 这个要修改
      [*]   Provide GDB scripts for kernel debugging  # 上一步修改之后，才有这个选项

检查下配置，

$ grep -E "(CONFIG_DEBUG_INFO|CONFIG_GDB_SCRIPTS|CONFIG_HELLO)=" .config
CONFIG_HELLO=y   # 编写的测试模块
CONFIG_DEBUG_INFO=y
CONFIG_GDB_SCRIPTS=y

上面这3项必须全都是y才行，然后开始编译。

$ make -j $(nproc)

检查编译成果：

$ ls arch/x86/boot/bzImage
$ ls vmlinux

$ cp arch/x86/boot/bzImage vmlinux ../   # 都copy到debug_linux目录下

bzImage 是 Linux 内核的标准引导映像，用于启动系统。
vmlinux 文件是未压缩的Linux内核映像，包含完整的内核代码、数据和符号信息，后续会用于调试

上面新编译出的内核中开启了debug选项，也内置了我们自己编写的模块。继续往下就可以测试新版本的内核了。

调试内核

为方便调试，这次就基于initramfs启动新编译的内核，主要还是使用上篇文章编译和运行新版本Linux内核中用到的QEMU和busybox等技术。

制作 initramfs

安装busybox和QEMU

$ # 用 yum 安装qemu-kvm
$ sudo yum install -y qemu-kvm

$ # 编译busybox
$ cd debug_linux
$ wget https://busybox.net/downloads/busybox-1.37.0.tar.bz2
$ tar xvf busybox-1.37.0.tar.bz2
$ cd busybox-1.37.0

$ make mrproper   
$ make menuconfig  # 一定要选择 Build static binary
$ make -j $(nproc)
$ make install

注意：编译busybox时，一定要选择编译成静态二进制文件。选项的路径是 Settings --> Build Options --> [*] Build static binary (no shared libs) 。

准备制作 initramfs 文件的目录结构。

$ cd debug_linux
$ mkdir initramfs_dir
$ cp -r busybox-1.37.0/_install/* initramfs_dir/

$ cat >> initramfs_dir/init << EOF
#!/bin/sh

mkdir /proc && mount -t proc none /proc

/bin/sh
EOF

$ chmod +x initramfs_dir/init

创建Makefile

initramfs:
    cd initramfs_dir && find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../initramfs.img

run:
    /usr/libexec/qemu-kvm \
        -kernel bzImage \
        -initrd initramfs.img \
        -m 256M \
        -nographic \
        -append "earlyprintk=serial,ttyS0 console=ttyS0 loglevel=8"

debug:
    /usr/libexec/qemu-kvm \
        -kernel bzImage \
        -initrd initramfs.img \
        -m 256M \
        -machine accel=tcg \
        -s \
        -S \
        -nographic \
        -append "earlyprintk=serial,ttyS0 console=ttyS0 loglevel=8 nokaslr"

这个Makefile里3个目标： + initramfs：制作initramfs.img 镜像文件 + run：用新的Linux内核和initramfs启动虚拟机。 + debug：以调试模式启动QEMU虚拟机，启动的时候会暂停住，等待GDB的连接和指令 + -machine accel=tcg ，由于用的是 qemu-kvm，虚拟机会默认启用kvm，导致无法正常调试。-machine accel=tcg配置关闭了kvm，使得调试得以进行。 + -s：表示在1234端口接受GDB的调试连接。 + -S：表示QEMU虚拟机会冻结CPU，直到远程的GDB输入相应控制命令。 + nokaslr：用于禁用内核地址空间布局随机化（KASLR），以便内核的内存地址保持一致。KASLR 是用于随机化内核加载的内存地址的安全措施。

> 在实际测试的过程中，用rmmod在宿主机上卸载`kvm`和`kvm_intel`两个内核模块后也可以顺利开展GDB调试。

测试运行

启动虚拟机前，先制作 initramfs.img 文件

$ make initramfs
$ ls
bzImage  initramfs_dir  initramfs.img  linux-6.14.6  linux-6.14.6.tar.xz  Makefile  vmlinux

运行 make run 正常启动QEMU。

$ make run

在QEMU虚拟机的启动过程中，可以看到其中有一行输出了 ********** Hello， World! ********** 。之后系统进入正常的shell环境中。

使用 Ctrl-a x 快捷键退出虚拟机。接下来调试kernel的启动过程。

运行和调试Linux内核

以调试模式启动QEMU虚拟机

$ make debug

启动后，QEMU 会监听在1234端口。打开另一个终端，使用gdb连接到QEMU的调试端口

$ cd debug_linux  # 这个目录下应该有 vmlinux 才行

$ gdb -ex "target remote 127.0.0.1:1234" vmlinux 
(gdb) b start_kernel   # 在linux的入口函数start_kernel上打断点
(gdb) b hello_init     # 打在hello模块上打断点  

(gdb) c   # 继续向下运行，QEMU会停留在 Booting the kernel. 对应的是 start_kernel 函数
(gdb) n 15   # 往下执行15行代码
925             setup_nr_cpu_ids();
(gdb) p command_line    # 检查传递给内核的参数
$1 = 0xffffffff8332e020 <command_line> "earlyprintk=serial,ttyS0 console=ttyS0 loglevel=8 nokaslr"
(gdb) p linux_banner
$2 = 0xffffffff823747e0 <linux_banner> "Linux version 6.14.6 (xxx) (gcc (GCC)
.1-3), GNU ld version 2.35.2-54.el9) #2 SMP PREEMPT_DYNAMIC xxx\n"
(gdb) c

(gdb) p message   # 检查变量值
$3 = "Hello, World!"
(gdb) set message = "Hello, Linux!"  # 修改message的值
(gdb) n 2   # 向下执行2行
13          printk(KERN_INFO "********** %s **********\n", message);
$(gdb) c  # 继续启动虚拟机

b、c、n、p、l 都是gdb调试的基础指令。

上面的gdb命令先是检查了command_line 和 linux_banner变量，分别是qemu-kvm 命令中传递给内核的参数，与内核的版本号以及编译环境信息。

之后又修改了自定义模块hello中的message变量的值，并检查修改之后的结果。修改之后向下执行2代码，观察QEMU中的情况，正好刚刚输出 ********** Hello Linux! **********。在GDB中对变量message的修改生效了！

通过上面的方法，可以一步步调试Linux内核的启动过程和执行过程，用于深入了解Linux的底层逻辑。

以上就是用gdb调试内核的基本用法。

总结

本文首先阐释了Linux内核模块的概念，并编写一个极简的hello代码，将其编译为内核模块，尝试加载到运行中的系统。之后又将代码集成到Linux源码中，编译到Linux内核里，使用gdb对该模块进行调试。

以上就是关于内核模块编写、使用，以及开发Linux内核的基础知识了。

如果想进一步了解关于Linux模块的相关内容，建议阅读 The Linux Kernel Module Programming Guide 这本小书。

编译和运行新版本Linux内核

Mon, 19 May 2025 11:29:40 +0800

暮春时节，咖啡店外的街道郁郁葱葱。

对天天使用Linux系统的人来说，内核是个既神秘又强大的存在。编译内核也是探索和学习Linux的一种方式，虽然不大可能真的将自己编译的内核用在桌面或者生产系统，也不大有能力为Linux内核贡献代码，但是了解内核的基本组成还是挺有趣的。

本文使用RockyLinux9作为编译机，编译最新版的Linux内核 6.14.6 版本，并编译busybox提供基础的shell环境。之后层层深入，从构建initramfs开始、制作rootfs、最后使用GRUB引导内核启动结束。

基础环境：

编译的host系统：RockyLinux 9 Busybox版本：1.37.0
内核源码版本：6.14.6 QEMU的版本：qemu-kvm-9.0.0

不同发行版本的glibc等基础软件有差异，不是所有的系统都能编译最新版本内核，比如CentOS 7编译Linux 6的源码就有问题。

编译Busybox和Linux

创建用于编译的目录结构，下载Busybox和Linux的源码，安装编译的依赖：

$ mkdir build_linux
$ mkdir run_linux 
$ cd build_linux
$ wget https://mirrors.aliyun.com/linux-kernel/v6.x/linux-6.14.6.tar.xz
$ wget https://busybox.net/downloads/busybox-1.37.0.tar.bz2
$ sudo yum install -y gcc make glibc-static flex bison openssl-devel \
                    ncurses-devel elfutils-libelf-devel

从Linux官网 kernel.org 下载Linux源码比较慢，这里选择从阿里云的镜像源里下载Linux源码。

解压和编译过程中，目录会大小膨胀，建议使用至少有 10GB 可用空间的分区来做编译和运行的环境。

build_linux 目录，用来保存下载和编译源码。
run_linux 目录，用来保存Linux运行所需的文件。

此外，上面yum安装的基础依赖不一定就是全面的，如果后续编译遇到问题，可能还需要安装缺失的特定依赖。

编译安装 busybox

Busybox 是非常知名的工具软件，里面实现了各种常用的Linux命令，可以提供一个轻量的shell环境，用于和kernel交互。

为了方便使用，需要将 Busybox 编译成静态的二进制文件，之后运行时就没有依赖了，编译静态二进制busybox的方法如下：

在make menuconfig 时的交互选择界面中，勾选 Build static binary (no shared libs)，路径是

Settings -->
    Build Options
    [*] Build static binary (no shared libs)`

下面是具体的编译命令

$ tar xvf busybox-1.37.0.tar.bz2
$ cd busybox-1.37.0
$ make mrproper   
$ make menuconfig  # 一定要选择 Build static binary
$ make -j $(nproc)

make mrproper，清理之前构建的中间产物，虽然我们是新下载解压的源码，但是编译前清理一下是个好习惯
make menuconfig 交互式选择编译选项，只需要开启Build static binary即可
make -j $(nproc) 使用系统上所有的CPU核心进行编译，加快编译速度，也可以用-j指定具体编译并发数。

验证编译出来的busybox二进制文件是否静态，是否能正常使用

$ ldd busybox 
        not a dynamic executable
$ ./busybox pwd

如果没报错，说明busybox的编译正常。

编译Linux内核

和上面的编译过程一样，编译Linux时也可以在make menuconfig的过程中，自定义编译选项和模块。我一般会选择关闭虚拟化，多媒体和声卡，加快编译速度。

[ ] Virtualization  
Device Drivers
  < > Multimedia support
  < > Sound card support

做好选择之后退出并保存，会存为 .config 文件。接下来编译Linux源码的操作，和编译Busybox差不多。

$ tar xvf linux-6.14.6.tar.xz
$ cd linux-6.14.6
$ make mrproper  
$ make x86_64_defconfig   # 生成针对 x86_64架构的默认配置文件
$ make menuconfig     
$ make -j $(nproc)  
$ file arch/x86/boot/bzImage
arch/x86/boot/bzImage: Linux kernel x86 boot executable bzImage, version 6.14.6 () #...
$ ls -lh  arch/x86/boot/bzImage 
-rw-r--r--. 1 root root 13M May 17 10:41 arch/x86/boot/bzImage

如果make时遇到中报错：X.509 certificates to be preloaded into the system blacklist keyring。

需要进行如下的menuconfig配置，将如下路径中的具体证书路径清空，保存，重新编译即可。

Cryptographic API
   > Certificates for signature checking
      > X.509 certificates to be preloaded into the system blacklist keyring   # 清空配置的证书路径

我的32核老服务器CPU在几分钟内就完成了编译，速度还是非常不错的。

生成的 bzImage 是用于启动引导的内核文件，是压缩格式的，保存的路径为 arch/x86/boot/bzImage。这个文件非常袖珍，只有13M大小，真是神奇。

make oldconfig 可以直接使用之前生成的 .config，而不用交互式选择模块。

使用新的Linux内核

QEMU是一款开源的仿真和虚拟化软件，可以模拟多种CPU架构和系统硬件。为简单起见，直接yum安装即可。

RockyLinux 9提供的qemu-kvm包集成了内核kvm虚拟化技术，可以提高QEMU模拟器的性能。 QEMU在不同发行版中内置的版本可能不一样，比如Debian 12中就推荐安装qemu-system-x86，并使用 qemu-system-x86_64 命令启动

$ sudo yum install -y qemu-kvm

将之前编译生成的busybox和bzImage文件都复制到run_linux 目录下，后续的生成的启动文件也都放在 run_linux 目录下。

$ cd run_linux
$ cp ../build_linux/busybox-1.37.0/busybox ./
$ cp ../build_linux/linux-6.14.6/arch/x86_64/boot/bzImage ./

initrd 、 initramfs、rootfs的区别

Linux中initrd、initramfs、rootfs的区别：

initrd（initial ramdisk）：通常是一个压缩的块设备映像，是initramfs的前身，早期Linux中有所使用。加载到内存后需要挂载为一个临时文件系统。启动过程较长，现在已经很少使用。
initramfs：基于内存的临时初始根文件系统，通常是cpio归档的格式，在系统启动过程中使用。在真正的rootfs被挂载之前，初始化硬件设备和加载必要的驱动（比如加载LVM模块），以便挂载真正的rootfs。系统启动过程结束后就不再需要，此时系统会切换到真正的rootfs。
rootfs：这里指Linux系统磁盘上的根文件系统，包含了启动后系统运行所需的目录和文件，比如/bin、/etc、/dev、/proc等。通常作为系统的主文件系统，所有其他文件系统都会在其上挂载。rootfs通常包含了系统的长期存储数据。一般用硬盘等介质。

GRUB的menuentry中可能还会使用initrd这个配置项名称，但指向的文件一般是nitramfs格式的。

initramfs启动

有些简单的内核调试可能是不需要硬盘和持久化的，这时用initramfs就很方便。

创建initramfs_dir，将busybox文件放到initramfs_dir/bin下，后续将initramfs_dir 目录打包成cpio格式的initramfs.img文件。等启动initramfs后，busybox在系统中的路径为 /bin/busybox。

$ mkdir -p initramfs_dir/bin
$ cp busybox initramfs_dir/bin/

创建启动文件initramfs_dir/init、内容如下

#!/bin/busybox sh

/bin/busybox mkdir /proc && /bin/busybox mount -t proc none /proc

/bin/busybox echo "Hello World."
/bin/busybox sh

脚本中做了一些简单的初始化操作，如果有需要，也可以做的更复杂些。

首先创建了 /proc 目录，然后挂载，有这个目录了就能运行ps命令
然后输出了“Hello World”
最后启动一个交互式的 sh，提供给用户操作

init脚本中所有命令都是以busybox的方式运行的。下面为init文件添加可执行权限，它会在内核加载之后启动。

$ chmod +x initramfs_dir/init

为了方便测试，接下来创建Makefile，用来管理 initramfs和QEMU的启动命令

initramfs:
    cd initramfs_dir && find . -print0 | cpio --null -ov --format=newc | gzip -9 > ../initramfs.img

run:
    /usr/libexec/qemu-kvm \
        -kernel bzImage \
        -initrd initramfs.img \
        -m 256M \
        -nographic \
        -append "earlyprintk=serial,ttyS0 console=ttyS0"

initramfs 目标用于创建新的 initramfs.img 文件
run 目标用于启动QEMU
- -kernel和-initrd参数指定了kernel文件和initramfs文件
- -m 指定了QEMU虚拟机的内存
- -nographic 指定不要启动图形界面
- -append 指定虚拟机的串口等信息

注意：makefile中的缩进是tab，不能是空格

接下来正式打包 initramfs和运行编译好的Linux。

$ make initramfs   # 生成 initramfs.img 文件
$ make run
...
Hello World.
/ # busybox ls
bin   dev   init  proc  root

/ # busybox uname -a
Linux (none) 6.14.6 #1 SMP PREEMPT_DYNAMIC Sat May 17 10:40:54 EDT 2025 x86_64 GNU/Linux

/ # busybox ps -ef  | busybox  head -5
PID   USER     TIME  COMMAND
    1 0         0:00 {init} /busybox sh /init
    2 0         0:00 [kthreadd]
    3 0         0:00 [rcu_gp]
    4 0         0:00 [rcu_par_gp]

可以看到内核版本，以及1号进程都和我们预设的一样。

注意： 命令前都需要加上 busybox 命令。

退出QEMU的方式：先按Ctrl-a 后按x。

这样启动的QEMU虚拟机运行在内存中，重启后，系统中所有的配置和修改都会丢失。如果要对数据进行持久化，可以创建一块虚拟磁盘作为系统的rootfs。

接下来测试rootfs的方案。

rootfs启动

为了摆脱busybox ls 这种麻烦的命令行方式，接下来，完善rootfs的目录结构。进入busybox的编译目录，继续执行 make install命令。

$ cd build_linux/busybox-1.37.0/
$ make install
$ ls -l  _install/usr/bin/wget
lrwxrwxrwx. 1 appweb appweb 17 May 17 11:54 _install/usr/bin/wget -> ../../bin/busybox   # wget命令是到busybox的软连接

会生成 _install 目录，里面包含各类常用的命令文件，都以软连接的方式指向二进制文件 bin/busybox 。里面的文件已经具备了基本的目录结构。

创建rootfs目录和rootfs.img虚拟磁盘，对rootfs.img执行格式化和挂载，并将busybox新生成的 _install 目录下的内容复制到 rootfs目录下。

$ cd run_linux
$ mkdir rootfs
$ dd if=/dev/zero of=rootfs.img bs=1024k count=50
$ mkfs.ext4 rootfs.img
$ sudo mount rootfs.img rootfs/
$ sudo chown $UID rootfs   
$ cp -r ../build_linux/busybox-1.37.0/_install/* rootfs/
$ sudo mkdir rootfs/{proc,dev,etc}
$ sudo mkdir rootfs/etc/init.d/

创建一个 50M 大小的文件，作为QEMU使用的虚拟磁盘
先将虚拟磁盘格式化为ext4，再挂载到rootfs目录下
将busybox的 _install 目录下的内容复制到 rootfs下

继续为 rootfs 创建其它基础目录结构和文件。创建 rootfs/etc/inittab，启动后的路径为 /etc/inittab，定义系统的运行级别和该级别下启动的进程，内容如下

::sysinit:/etc/init.d/rcS
::respawn:-/bin/sh
::ctrlaltdel:/bin/umount -a -r

inittab文件的第1列通常是id，第2列通常是数字0-6，但是我们这个没这么复杂，仅指定了3个动作触发相应的任务

sysinit 表示系统初始化阶段，指定执行 /etc/init.d/rcS 文件做初始化的任务
respawn表示如果进程终止，则启动一个登录的/bin/sh
ctrlaltdel 表示用户按下Ctrl+Alt+Del 组合键时执行的命令，卸载所有文件系统，并以只读方式重新挂载

创建 rootfs/etc/init.d/rcS，内容如下，会执行etc/fstab文件中指定的挂载操作

#! /bin/sh

/bin/mount -a

创建 rootfs/etc/fstab ，内容如下，挂载 proc 文件系统

proc            /proc   proc    defaults    0   0

给etc/init.d/rcS赋予可执行权限。然后卸载 rootfs

$ sudo chmod +x rootfs/etc/init.d/rcS
$ sudo umount rootfs

编写新的 Makefile.rootfs，用于让QEMU以rootfs的方式启动内核

run:
    /usr/libexec/qemu-kvm \
                -kernel bzImage \
                -m 256M \
                -nographic \
                -hda rootfs.img \
                -append "root=/dev/sda rw earlyprintk=serial,ttyS0 console=ttyS0 loglevel=8"

整体上和initramfs的QEMU启动命令差不多，有细微差别 + -hda rootfs.img 将rootfs.img 作为额外硬盘挂载到QEMU虚拟机中。 + 不需要 initrd 参数指定initramfs文件了。 + -append中指定了kernel的参数 + root=/dev/sda：指定根文件系统的位置。rw 或 ro：指定根文件系统以读写或只读模式挂载。 + 还可以指定 init 程序：init=/path/to/init。没指定的话，默认会尝试/sbin/init、/etc/init、/bin/init、/bin/sh 这些文件。

启动rootfs的虚拟机，使用make 命令的-f选项指定为rootfs编写的Makefile文件Makefile.rootfs

$ make run -f Makefile.rootfs

之后进去系统就可以直接执行命令了

~ # ls -l /bin/ls
lrwxrwxrwx    1 0        0                7 May 17 09:07 /bin/ls -> busybox

~ # df -hT
Filesystem           Type            Size      Used Available Use% Mounted on
/dev/root            ext4           41.8M     10.1M     28.3M  26% /
devtmpfs             devtmpfs      106.1M         0    106.1M   0% /dev

~ # free -m
             total       used       free     shared    buffers     cached
Mem:           227         15        211          0          0          2
-/+ buffers/cache:         13        213
Swap:            0          0          0

可以看到 ls 命令是到 busybox 文件的软连接。df和free命令也能正常显示

如此就具备了一个基本的Linux的雏形。此时修改系统的文件和配置，内容就会被持久化到虚拟磁盘中了，实际上就是 rootfs.img 这个文件中。

配置GRUB

GRUB 是Linux系统中常用的引导加载程序，负责在计算机启动时加载操作系统内核并移交控制权。与之相关的配置文件一般位于/boot/ 目录下。接下来创建新的虚拟磁盘，并使用parted划分为2个分区，一个用于GRUB引导，一个用于主分区。

接下来，使用GRUB把我们的新Linux系统打造的更像样一些。

$ dd if=/dev/zero of=disk.img bs=1M count=50   # 50MB大小的磁盘

# 使用GPT分区
$ sudo parted disk.img mklabel gpt
$ sudo parted disk.img mkpart primary 1MiB 2MiB  # 第一个分区
$ sudo parted disk.img set 1 bios_grub on       # 标记为 BIOS Boot 分区
$ sudo parted disk.img mkpart primary ext4 2MiB 100%   # 第二个分区，根分区

$ sudo parted disk.img print  # 查看分区表
Number  Start   End     Size    File system  Name     Flags
 1      1049kB  2097kB  1049kB               primary  bios_grub
 2      2097kB  52.4MB  50.3MB  ext4         primary

创建了50M大小的disk.img文件，作为后续QEMU挂载使用的虚拟磁盘。用parted标记为gpt格式
划定了2个分区，1M的那个用于BIOS Boot分区，剩余的空间是rootfs的根分区，并格式化为ext4

将新创建的disk.img 也挂载到本地，这里使用 losetup 工具挂载。

$ sudo losetup -Pf disk.img  # 挂载
$ losetup -a      # 查看挂载，获取实际的盘符，可能是loop0，也可以是其他的编号

$ ls /dev/loop0*  
/dev/loop0  /dev/loop0p1  /dev/loop0p2   # 可以看到虚拟磁盘的设备和分区的设备了

$ sudo mkfs.ext4 /dev/loop0p2  # 谨慎确认后操作

$ mkdir disk 
$ sudo mount /dev/loop0p2 disk

注意： 必须确定 /dev/loop0 是我们新创建的虚拟盘，如果误操作到物理磁盘，会产生主机系统损坏的严重后果。

挂载之后可以看到有/dev/loop0p1和/dev/loop0p2 两个分区（前提是之前没有挂载过文件）。用mount进行的虚拟磁盘mount也会占用设备编号，我的环境中是 loop0，在你的设备中不一定，操作前注意用losetup -a 检查下实际的盘符，并修改为自己环境的配置。
挂载之后将根分区格式化为 ext4
将格式化好的根分区挂载到本地新创建的disk目录，然后就可以往里面写数据了；

下面为新磁盘写入rootfs的内容，我们直接从之前的rootfs.img 里复制过来

$ sudo mount rootfs.img rootfs
$ sudo cp -r rootfs/* disk/

使用grub2-install 往虚拟磁盘中安装GRUB 2引导加载程序。并将 bzImage 内核文件复制到 boot 目录下

$ sudo grub2-install \
  --target=i386-pc \
  --boot-directory=disk/boot \
  /dev/loop0   # 操作前谨慎确认

$ sudo cp bzImage disk/boot/

注意： 必须确定 /dev/loop0 是我们新创建的虚拟盘，如果误操作到物理磁盘，会产生主机系统损坏的严重后果。

继续创建和编写GRUB 文件 disk/boot/grub2/grub.cfg，指定加载模块和内核文件与内核参数。

# Begin /boot/grub2/grub.cfg
set default=0
set timeout=5

insmod part_gpt
insmod ext2
set root=(hd0,2)

menuentry "Linux 6.14.6" {
    linux       /boot/bzImage   root=/dev/sda2 ro console=ttyS0,115200n8 earlyprintk=serial
}

卸掉挂载，然后用QEMU启动系统

$ sudo umount rootfs
$ sudo umount disk
$ /usr/libexec/qemu-kvm -hda disk.img  -nographic

很快就能看到GRUB界面了！

GRUB结束后继续启动，就进入了内核启动阶段，最终就能看到一个不太完善的Linux系统了。

至此，我们自己编译的当前最新版本Linux内核就成功的通过GRUB引导了。

总结

首先，我们编译了一个Linux内核，又编译了busybox为新内核提供简单而又基础的shell环境。通过制作initramfs在QEMU中快速启动新内核，方便快速测试和验证；通过虚拟磁盘构建rootfs的方式，实现虚拟机数据的持久化；最后，通过配置GRUB引导，使得这个新的系统看起来更加有模有样。

但实际上，busybox提供的功能十分有限，缺乏大量的基础软件，远远不能作为真实的系统使用。如要想要进一步深入了解如何构建一个真实的Linux发行版，建议查看Linux From Scratch，书中逐步讲解了如何从头编译一个完整Linux系统，这本书也不长，主要的篇幅都是编译过程，读起来并不吃力。

本篇博客就到这里为止。后续还有一篇博客，将讲解如何开发一个简单而又无用的Linux内核模块，并使用gdb对其进行调试。

博客归来2

Sun, 11 May 2025 14:32:36 +0800

2025年5月11日拍摄于黄昏的浙大紫金港校园。正如那句老话，道路是曲折的，前景是光明的。

这个博客已经开通了很久，眼尖的朋友可能已经发现博客最近发生了重大改版。

是的，近期我用 Flask 重写了本博客，替代用了好些年的Typecho。想想从大学时候写博客，用的wordpress，后续换到更轻量的typecho，其实都不算满意，主要原因就是不能随心所欲的定制，毕竟和PHP不熟。也看到很多人在用github或者其它静态页面工具搭建站点，但我更希望能自己写一套博客系统，而且必须用Python写，必须是动态的。

起源

甚至很久之前就写好了前台相关的后端服务，用semantic-ui写出了一部分的页面。后来卡壳就停下了，不知道markdown的显示效果为什么这么差，不知道后端的文章编辑器该如何下手，以及各种想想都头大的问题。

后来，我甚至粗略看了Vue、htmx，认真学了React相关的课程，但还是不得其门而入。前端就像一头猛虎拦住了去路。

干活

今年春天，忽然想起来要抛弃一切胡思乱想，就用传统的Bootstrap，服务端渲染，加一点jquery，应该就能满足这个博客系统的要求了。

说干就干，看了1个小时的bootstrap视频学习网站布局，然后开始动手，将原来的前端代码全部删除，用bootstrap搭出一个现在流行的极简样式。居然没有那么复杂。

从3月下旬开始，一写就停不下来了：周末写、熬夜写、工作日的午休时间写。写完前台写后台，写完后端写前端，整完了代码整自动化发布。把原计划要读的书都搁置了，全部的休息时间用来写代码。期间还发生了家里homelab主服务器sd卡损坏，备份不完整导致PostgreSQL 数据只能回滚到4个月前的事情，把许多重要服务做了紧急迁移恢复。

一路上，遇到许多之前没考虑到问题，也用一些奇思妙想解决了奇怪的问题，有时候做梦都在写。当然，AI在这个过程中也助力不少，虽然没有用copilot，但对于拿不准的前端问题，问AI的话，往往有不错的效果。

发布

终于，五一劳动节期间，将新版本的博客系统推出了。

当然，这套系统不论是用户测体验，还是管理后台功能，或是代码质量与性能，都还有许多需要优化的地方。这次先发布初版，后续慢慢优化。

重要的是内容，博客已经停更很久了。主要原因是当我切换到Joplin笔记软件后，体验非常舒适，许多笔记我都记录在上面了，但是由于对原来的博客系统不是很喜欢，也就没有继续整理发表的心情了。这次一定要坚持下去，近期争取每周发表一篇，以后也要至少每月1篇。自研的这套博客系统会给我持续更新下去的动力。

虽然，我没有成为全栈工程师的野心，对前端依旧没有多少兴趣，但是掌握一些前端才能具备开发完整产品的能力。因此，这个博客，就是我的第一个作品。

总结

或许博客这种载体已经过时了，但是，就像我homelab上自建的笔记、RSS、即时通讯、开发套件、影音服务一样，要做自己信息的主人，特立独行，不要被时代潮流里过剩的信息淹没。

2014年的博客归来是一次重大的变化，那次换了域名和开源系统。这次将文章写在自己的代码上，要更长久的坚持下去。

博观而约取，厚积而薄发，勉之！

Vagrant和Vagrantfile入门

Wed, 22 Feb 2023 00:08:00 +0800

Vagrant 是由hashicorp公司（该公司还开源了Consul、Terraform等工具）开源的用于构建和管理虚拟机环境的工具，对于快速构建开发环境十分有用。Vagrant使用Vagrantfile进行虚拟机编排，和docker-compose有些类似，只不过Vagrant管理的对象是虚拟机，Vagrant支持VirtualBox、 VMware Fusion 和 Hyper-V 等许多虚拟化产品。本文中基于VirtualBox做演示。

对于开发人员来说，Vagrant可以快速构建一致性的开发环境，并通过分享Vagrantfile快速创建相同的开发环境，是一个很值得了解的工具。Vagrantfile是Vagrant的核心，直到vagrant如何创建虚拟机。

实践环境

系统：Ubuntu 22.04
Vagrant版本：Vagrant 2.3.4
VirtualBox版本：7.0.6

各操作系统上安装Vagrant的方法见官方链接 [Install | Vagrant | HashiCorp Developer](https://developer.hashicorp.com/vagrant/downloads)

为什么要用Vagrant？

对运维工程师来说，学习新软件的第一步肯定是要尝试自行搭建一套环境，尤其是Kubernetes、Ceph等大型软件，一般需要多台机器构建分布式集群。使用Vagrantfile可以快速定制多虚拟机组成的服务器基础环境。
对研发和测试工程师来说，通过干净的虚拟机环境测试，有也助于复现、排除和定位软件问题。

Vagrant基础

Vagrant box

box的概念可以对应docker镜像，也即虚拟机镜像，box是本机全局共享的。Vagrant提供了类似docker hub的在线镜像平台：https://app.vagrantup.com ，可以选择自己需要的基础镜像。

执行vagrant box 命令可以查看和box相关的操作，常用的有如下几个子命令：

add：在线下载box
list：列出当前机器上的box
remove：删除box

默认从官方下载box比较慢，许多发行版都提供了用于vagrant的box文件，可以从国内的镜像源下载并添加到vagrant即可使用。比如，创建 ubuntu/xenial 这个box。

$ vagrant box add ubuntu/xenial \
    https://mirrors.ustc.edu.cn/ubuntu-cloud-images/xenial/20210928/xenial-server-cloudimg-amd64-vagrant.box
$ vagrant box list
ubuntu/xenial   (virtualbox, 0)

常用的Vagrant 指令

vagrant init 是初始化Vagrantfile的命令

vagrant up 根据当前目录下的Vagrantfile创建和启动虚拟机

vagrant destroy 销毁Vagrantfile创建的虚拟机

vagrant ssh/scp ssh相关的子命令，可以使用ssh协议登录虚拟机，scp子命令则可以在虚拟机和物理机之间拷贝文件

vagrant status/global-status：status查看当前环境下的虚拟机状态，global-status 则可以查看本机上所有的虚拟机状态。

vagrant halt 关闭虚拟机

vagrant reload重启，基于更新后Vagrantfile更新虚拟机

vagrant port 查看虚拟机和物理机端口映射

以下是基础的vagrant 指令操作

创建Vagrantfile，-m 参数用于创建简化的Vagrantfile

$ mkdir /tmp/vagrant
$ cd /tmp/vagrant
$ vagrant init generic/centos7 -m   

$ cat Vagrantfile      
# -*- mode: ruby -*-
# vi: set ft=ruby :

Vagrant.configure("2") do |config|
  config.vm.box = "generic/centos7"
end

启动Vagrantfile定义的虚拟机，默认的provider一般是virtualbox，也可以使用--provider指定。

$ vagrant up --provider=virtualbox

查看vagrant管理的虚拟机，默认创建的虚拟机名叫default

$ vagtrant status 
Current machine states:
default                   running (virtualbox)

查看vagrant的端口映射，将虚拟机的22号端口映射到本地2222端口

$ vagrant port  
    22 (guest) => 2222 (host)

登录到默认虚拟机

$ vagrant ssh default
[vagrant@centos7 ~]$ exit

实际上等价于 ssh -i .vagrant/machines/default/virtualbox/private_key -p 2222 vagrant@127.0.0.1 ，登录映射到本地的 2222端口。.vagrant 目录下有许多vagrant生产的文件。

关闭虚拟机

$ vagrant halt default 
==> default: Attempting graceful shutdown of VM...
==> default: [vagrant-hostsupdater] Removing hosts on suspend

关闭后，虚拟机的状态变为 poweroff

$ vagrant status 
Current machine states:
default                   poweroff (virtualbox)   # 虚拟机状态变为poweroff

The VM is powered off. To restart the VM, simply run `vagrant up`

销毁虚拟机

$ vagrant destroy     
    default: Are you sure you want to destroy the 'default' VM? [y/N] y
==> default: Destroying VM and associated drives...

销毁之后，虚拟机的状态变为 not created

$ vagrant status 
Current machine states:

default                   not created (virtualbox)  # 状态变为 not created

以上创建的虚拟机，在virtualbox的GUI界面上也能看得见，也可以使用virtualbox进行管理。

到这里为止基本上就完成了Vagrant的入门，也没什么了不起的，对吧？别着急，Vagrant的精华在Vagrantfile，精彩的在后面。

定制Vagrantfile

在上一部分中，仅仅使用了Vagrant生成的默认Vagrantfile，Vagrantfile使用的是ruby的语法，非常灵活和强大，我也不会ruby，就老老实实依葫芦画瓢按照需求来写。

Vagrant的provisioning 功能可以在vagrant up 过程中执行安装软件、运行指定命令等，用来更好的按需定制化系统。Provisioning | Vagrant | HashiCorp Developer

Vagrant 有插件机制，支持的插件列表见链接 Available-Vagrant-Plugins ，Vagrant可以对plugin执行install、uninstall、list、update等操作。

比如，安装 vagrant-hosts 插件，用于管理虚拟机的/etc/hosts文件

$ vagrant plugin install vagrant-hosts
$ vagrant plugin list
vagrant-hosts (2.9.0, global)
vagrant-scp (0.5.9, global)

以下是一个比较完整的定制化Vagrantfile，涉及了网络、磁盘、内存、CPU、系统初始化等方面的定制，基于这个Vagrantfile，将Vagrantfile修改成自己需要的样子。

# -*- mode: ruby -*-
# vi: set ft=ruby :

$init_script = <<-'SCRIPT'
     setenforce 0
     sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
     unlink /etc/localtime
     ln -s /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
SCRIPT

$ext_mount = <<-'SCRIPT'
  parted -s /dev/sdb mklabel gpt mkpart primary ext4 0% 100%
  mkfs.ext4  /dev/sdb1
  mkdir /data
  mount -t ext4 /dev/sdb1 /data
  echo "/dev/sdb1 /data ext4 defaults 0 0" >> /etc/fstab
SCRIPT

Vagrant.configure("2") do | config |
    config.vm.box = "generic/centos7"

    config.vm.provision "shell", inline: "systemctl stop firewalld.service"
    config.vm.provision "shell", inline: $init_script
    config.vm.provision "shell", inline: $ext_mount
    config.vm.provision "file", source: "~/.vimrc", destination: "~/.vimrc"

    config.vm.provision "hosts" do | host |
      host.add_host '192.168.56.11', ['node-1']
      host.add_host '192.168.56.12', ['node-2']
      host.add_host '192.168.56.13', ['node-3']
    end

    (1..3).each do |i|
      config.vm.define "node-#{i}" do | node |
        node.vm.hostname = "node-#{i}"
        node.vm.disk :disk, name: "data", size: "10GB"

        node.vm.provider "virtualbox" do | vb |
          vb.customize ["modifyvm", :id, "--memory", "1024"]
          vb.customize ["modifyvm", :id, "--cpus", "2"]
        end

      end
    end

    config.vm.define "node-1" do | node |
        node.vm.network "private_network", ip: "192.168.56.11"
    end

    config.vm.define "node-2" do | node |
        node.vm.network "private_network", ip: "192.168.56.12"
    end

    config.vm.define "node-3" do | node |
        node.vm.network "private_network", ip: "192.168.56.13"
    end
end

启动上面定义的Vagrantfile

$ VAGRANT_EXPERIMENTAL=disks vagrant up

环境变量 VAGRANT_EXPERIMENTAL=disks的作用是，本Vagrantfile中使用的disks相关功能还在实验阶段，如果不加环境变量，功能将无法正常使用。如果更新了Vagrantfile，在使用vagrant reload的时候也需要加上这个环境变量。

接下来解释下这个Vagrantfile每一部分所做的事情。

首先定义了2个变量init_script和ext_mount，自定义服务器创建时需要执行的初始化操作。这种多行字符串变量的定义方法叫 Heredoc，Bash中也有类似的操作。
do/end 相当于 {}，也可以用{}替换，用于定义一段代码块。
test do |x| ... end，在这种语句结构中，两个竖线中的 x 是局部变量，用于接收前面语句抛出来的值。
在 config.vm.provision 几行，使用了shell和file这两个内置的Provisioner。在这个过程中可以定义许多主机初始化操作。
在 config.vm.provision "hosts" 一行中，使用了前面安装的vagrant-hosts插件，为所有机器都添加了/etc/hosts静态解析。
(1..3).each do |i| ... end 这里是个循环，分别将1、2、3赋值给i，使用这个变量定义了node-1、node-2和node-3这三台主机。并定制了主机的内存、CPU资源和额外data硬盘等。
node.vm.network "private_network" 这3处代码则分别定义了3个节点的额外网卡和ip。
剩余的语句基本上就是赋值和函数执行一类的，没什么好说的，依葫芦画瓢即可，遇到特殊需求再google搜索。

启动Vagrant之后，继续验证主机是否符合预期。

$ vagrant status 
Current machine states:

node-1                    running (virtualbox)
node-2                    running (virtualbox)
node-3                    running (virtualbox)

$ vagrant ssh node-3
Last login: Tue Feb 21 23:37:03 2023 from 10.0.2.2

[vagrant@node-3 ~]$ df -hT /dev/sdb1 
Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/sdb1      ext4  9.8G   37M  9.2G   1% /data

[vagrant@node-3 ~]$ ip a s eth1
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 08:00:27:6d:39:57 brd ff:ff:ff:ff:ff:ff
    inet 192.168.56.13/24 brd 192.168.56.255 scope global noprefixroute eth1
       valid_lft forever preferred_lft forever
    inet6 fe80::a00:27ff:fe6d:3957/64 scope link 
       valid_lft forever preferred_lft forever

[vagrant@node-3 ~]$ nproc 
2

[vagrant@node-3 ~]$ free -m
              total        used        free      shared  buff/cache   available
Mem:            990         130         683          12         176         708
Swap:          2047           0        2047

[vagrant@node-3 ~]$ tail -3 /etc/hosts
192.168.56.11 node-1
192.168.56.12 node-2
192.168.56.13 node-3

[vagrant@node-3 ~]$ systemctl status firewalld
● firewalld.service - firewalld - dynamic firewall daemon
   Loaded: loaded (/usr/lib/systemd/system/firewalld.service; enabled; vendor preset: enabled)

可以看到主机的初始化完全符合我们的定义。

为什么要使用Vagrant？

我个人总结Vagrant有如下几点优势：

Vagrant十分强大，也有很丰富的插件可以选择：Available Vagrant Plugins · hashicorp/vagrant Wiki · GitHub 。
十分灵活的配置方法，且易于分享，简化系统初始化和配置过程。
虚拟机可以弥补某些测试场景下Docker的不足，比如需要特定的操作系统版本和内核。
对于网络、集群搭建等需要隔离和干净环境的需求，vagrant是比较方便。

VimScript：退出文件时自动关闭各种缓冲区(Buffer)

Fri, 08 Apr 2022 23:37:00 +0800

经过调教的vim，肯定有很多插件，比如nerdtree，python-mode等等，很多插件在使用过程中，都通过新建buffer来展示其提供的内容。出于习惯，使用q退出文件，当时vim上还有许多插件的buffer未退出，需要额外的指令执行退出(qa)。怎么在退出文件时，同时退出其它buffer？本文以vim初学者的，编写了一段vimscript实现该功能。

问题背景

经过一段时间的vim 调教，写代码时，vim 经常是下面的界面：

整个窗口分为好几块，分别是：

左上：nerdtree 文件目录列表窗口
下方：代码运行结果窗口
左上：代码编辑窗口
左中：代码检查窗口

除了代码文件编辑窗口，其它窗口都是起辅助作用，因此，当退出代码编辑之后，应该要自动关闭其它窗口。

代码实现

为了实现这个功能，研究了下vimscript，使用如下代码，基本实现了该需求。

autocmd WinEnter * call s:CloseBuffersIfAllFileClosed()

function! s:CloseBuffersIfAllFileClosed()
    let open_count = 0
    let winbufs = winnr("$")

    for buf in getbufinfo()
        let buffertype = getbufvar(buf.bufnr, '&buftype', 'ERROR')
        if empty(buffertype) && buf.loaded == 1
            let open_count += 1
        endif
    endfor

    if open_count == 0
        qa
    endif
endfunction

这段代码逻辑很简单，很像伪代码，功能就是判断buffer的状态，如果没有打开文件的buffer，就执行qa退出所有。

通过 getbufinfo()函数获取所有的buffer信息，遍历所有的buffer，并获取其类型和loaded状态。

如果buffer类型是"" 空字符串，表示buffer对应的是正常文件
如果loaded状态为1，则表明文件已加载。

根据这两个状态识别所有的buffer，从而判断是否有文件在打开，如果没有打开的文件，则vim自动执行qa。

将这段代码加入到 ~/.vimrc中，重新打开文件编辑即可生效。

其它相关

vim中其他和buffer相关的基础命令：

vim中使用 buffers 命令也可以在vim中获得buffer列表，使用buffers!，还可以额外获得unloaded状态的buffer情况。
vim中使用help buftype，可以看到所有buffer可能的状态，如nofile、help、quickfix

参考：

vimscript 基础语法：http://blog.chalda.cz/2018/08/07/Vim-script-notes.html

一句话crontab实现防ssh暴力破解

Fri, 26 Nov 2021 21:55:00 +0800

将vps在公网上，难免会有居心叵测的人扫描，及时换了非标准的端口，依旧难以避免。因此编写一条Bash命令，放在crontab里，发现坏人立刻封掉ip。

一句话命令如下：

$ crontab -l
* * * * *  journalctl -u ssh.service --since="24 hours ago" | awk '/Failed password/{if(NF>15){ips[$13]++}else{ips[$11]++}}END{for(ip in ips){if(ips[ip]>3){print ip}}}' | while read ip; do grep $ip$ /etc/hosts.deny > /dev/null || echo "ALL: "$ip | sudo tee -a /etc/hosts.deny ; done

功能：24小时内输错5次ssh密码的客户端ip，将立刻被添加到 /etc/hosts.deny 文件里做黑名单处理。

简单解析：

该条语句可以按三个管道符号进行分割，下面分别讲解。

管道的第一部分：使用 journalctl 命令查询最近24小时内的登录日志，该命令适用于使用systemd的系统，如果非systemd，可以换成从 /var/log/secure 文件过滤日志。

管道的第二部分：主要是awk过滤登录失败日志，关键字Failed password。对登录失败的ip地址进行统计，输出失败次数大于3次的ip地址。此处用到了awk的数组功能做统计。

管道的第三部分：去重，避免重复添加IP到/etc/hosts.deny文件中。使用while语句判断ip地址是否已经在 /etc/hosts.deny中，如果不在，则使用tee命令进行追加。

该命令不仅实用，而且还很有趣。个人以为十分有学习价值。