技术笔记整理

这份配置记录面向没有域名、又希望在国内服务器上以 HTTPS 方式提供 DoH 入口的场景，核心做法是为公网 IP 生成包含 IP SAN 的自签证书，再由本地客户端手动信任或跳过校验，以避免使用容易受限的 UDP/TCP 明文 DNS。正文给出了 OpenSSL 命令，将证书和私钥放在 /etc/nginx/ip-ssl，并解释了 req -x509、-nodes、rsa:2048、有效期、CN 以及 subjectAltName=IP 的作用，其中 SAN 是让证书明确匹配 IP 的关键。文章同时区分了自签证书与受信 CA 证书：前者免费、快速、适合内网测试或可控客户端，但默认不被浏览器和系统信任；后者更适合公网正式生产环境，通常依赖域名验证。nginx 部分展示了监听自定义 HTTPS 端口并启用 HTTP/2，再把 /dns-query 反代到本机 AdGuard Home DoH 服务的配置，同时关闭后端证书校验。需要注意的是，外层客户端到 nginx 可以使用 HTTP/2，但 nginx 到 AdGuard Home 被强制为 HTTP/1.1，并清空 Connection 头，以规避后端 HTTP/2 兼容性、Keep-Alive 行为不一致导致的 EOF 或 TLS handshake error。最后还补充了 X-Real-IP、X-Forwarded-For 透传，以及在 AdGuardHome.yaml 的 http 段开启 x_forwarded_for，让后台显示真实客户端 IP 而不是 127.0.0.1。该记录适合自建 DNS、反代 AdGuard Home、需要理解 IP 自签证书边界的运维或后端开发者参考。

服务器与部署

2025年12月6日1 分钟

关于“服务器配置与部署”类别

“服务器配置与部署”类别应围绕服务器环境准备、服务上线、运行维护和相关配置规则建立清晰边界，帮助读者在浏览或归档时快速判断内容归属。该类别的核心价值不只是收纳文章，而是说明为什么需要单独设置这一分类、它承担什么用途，以及哪些问题不应混入开发实现、应用使用或其他主题中。内容范围可覆盖部署前后的环境配置、服务运行条件、运维规则、上线流程和与服务器管理直接相关的话题，但需要通过准则避免分类泛化。分类说明还应明确它与既有类别的差异，尤其是在文章同时涉及代码实现、工具使用或系统维护时，给出优先归类的判断依据。若站点已有相近分类，也需要评估是否保留独立类别、合并到其他类别，或拆分出更细的子类别。整体上，这一类别适合用于规范站点信息架构、减少文章归档混乱，并为后续服务器部署与维护类内容提供稳定的组织框架。

AI 大模型开发

2025年12月6日14 分钟

langfuse追踪Trace

这篇笔记聚焦 Langfuse 在 LLM 应用中的调用追踪用法，适用于 OpenAI、LangChain 或自定义 Agent 这类需要观测请求链路的场景。正文先把 Langfuse 定位为面向大模型应用的 observability 平台，说明它可以记录一次调用的上下文、输入输出、耗时、错误、Token 成本、评分注释，并通过 Web UI 辅助分析。核心概念上，Trace 被解释为一次完整用户请求的顶层调用上下文，Span 则是 Trace 内部的子步骤，可以对应 OpenAI 调用、工具函数、向量检索或其他业务动作，并拥有自己的 start/end 生命周期。实现部分给出 Python 封装示例：通过环境变量初始化 Langfuse 客户端，创建 trace 与 span，在调用前写入 messages 作为 input，在调用结束后用 span.end 和 trace.update 记录最终 output。文章特别强调流式 GPT 响应默认不方便自动捕捉完整输出，因此需要在异步迭代 chunk 时用字符串累积 full_response，再把完整结果写回 Langfuse；异常路径则记录 error 后继续抛出。读者可以借此理解如何为自定义流式聊天接口补上可视化追踪、性能排查、错误定位和后续评估所需的数据基础。

AI 大模型开发

2025年12月6日22 分钟

OpenAI工具调用

这篇笔记围绕 OpenAI Chat Completions 的工具调用机制，说明模型如何在收到 messages 与 tools 定义后，通过 tool_calls 返回要调用的函数名和参数，再由本地代码执行函数并把结果回填给模型生成最终回答。示例从“北京天气”查询入手，给出 get_weather 的工具 schema 写法，包括 function name、description、parameters、required 等字段，并展示 tool_choice="auto" 下模型自行判断是否调用工具的流程。实现部分使用 AsyncOpenAI 封装流式服务，先非流式请求检测 tool_calls，解析 JSON 参数、执行本地函数，再按 assistant 的 tool_calls 记录和 tool 角色消息补齐上下文，最后二次 stream 请求输出自然语言结果，强调 tool_call_id 必须与原调用保持对应。后半部分把单个函数判断抽象为 BaseTool 注册器，通过类变量 registry 管理工具，利用 inspect.signature 自动生成参数 schema，并提供 register、call、acall 等方法支持同步和异步调度。笔记还解释了 @classmethod 的作用，说明类方法适合用于工具注册、访问类变量和无需实例化的统一管理，并与 staticmethod、普通实例方法做了对比。整体适合正在把 OpenAI 工具调用接入 Python 后端、需要理解消息拼接顺序、工具 schema 生成和函数调度封装的开发者阅读。

Python 开发

2025年12月6日18 分钟

s3上传文件sdk

这份笔记围绕兼容 S3 API 的 Python 异步文件上传封装展开，适用于 AWS S3、MinIO 等对象存储的接入场景。代码基于 aiobotocore 创建异步 S3 客户端，并用 aiofiles 读取本地文件，封装了普通 put_object 上传和 Multipart Upload 分块上传两条路径，同时支持自定义 endpoint、bucket、region、访问密钥和 Content-Type。普通上传会先读取完整文件再提交，调用方式简单，适合体积较小或对内存压力不敏感的文件；分块上传则以 8 MiB 为块大小，通过 asyncio.Semaphore 将并发上传限制在 4 路，并在完成前收集每个分片的 ETag 与 PartNumber 用于组装。文章还补充了对象键生成和 CDN URL 拼接方法，示例中通过 MinIO 配置构造客户端，分别演示普通上传与流式分块上传后返回访问地址的用法。分块说明部分强调了这种方案在大文件上传中的价值：降低一次性内存占用、提升网络吞吐，并让单个分片失败时具备更明确的重试边界。需要注意的是，普通上传示例虽然使用异步文件读取，但仍会把文件内容读入内存；而分块上传依赖同一个 async 上下文管理文件和 S3 客户端，更适合已经在 asyncio 环境中处理文件上传的后端开发者或对象存储接入场景。

Python 开发

2025年12月6日16 分钟

uv包管理器

这篇笔记围绕 uv 作为新一代 Python 包管理器的日常使用展开，重点说明它如何在兼容 pip、requirements.txt 和 pyproject.toml 的同时，通过 Rust 实现、缓存、内置虚拟环境和锁文件机制提升依赖安装速度与环境一致性。正文给出从 curl 安装、配置 PATH、检查 uv 版本，到使用 uv pip install、uv venv、uv pip compile 管理依赖和生成锁文件的基础流程，并特别强调 uv 默认会依据当前终端中的 python 路径选择解释器。文章还记录了在项目中指定 Python 3.12 创建 .venv、激活环境、验证解释器路径，以及从已有 requirements.txt 平滑迁移到 uv init、uv add 和 pyproject.toml 的操作方式。关于环境模型，作者将 Python 项目与 Maven、npm/yarn 类比，解释“共享解释器、隔离依赖”的实践：多个项目可以复用系统 Python，但各自维护独立 .venv 和 site-packages。后半部分对 pip、conda、uv 的适用场景做了区分：uv 更适合 Web、AI 项目和 CI/CD 中的快速构建，conda 更偏向需要 C/Fortran 依赖的科研计算，pip 则适合作为通用基础工具。文章最后用 requests 版本约束示例解释依赖冲突，指出 uv 相比传统 pip 会先构建依赖树、解析约束并通过锁定文件减少版本漂移，适合希望改造 Python 项目依赖管理流程的开发者参考。

Python 开发

2025年12月6日17 分钟

sqladmin管理工具

SQLAdmin 被定位为适合 FastAPI 项目的 SQLAlchemy 管理后台工具，提供类似 Django Admin 的模型管理体验，并通过 Tabler/Bootstrap 风格界面自动生成 CRUD、搜索过滤、多数据库管理和可扩展认证能力。文章明确了它的模型边界：必须基于 SQLAlchemy ORM，兼容 SQLAlchemy 1.x 与 2.x，0.15.0 之后全面支持 2.x，但不支持 Tortoise ORM 和 Django ORM。围绕异步 Python 项目的选型，内容对比了 SQLAlchemy 2.0 async、Tortoise ORM 与 asyncpg，指出 SQLAlchemy 2.0 在原生异步 API、声明式映射、类型提示、事务语义和长期维护方向上更适合需要强 ORM、类型检查与扩展性的 FastAPI 场景。示例部分使用 SQLite 搭建完整后台：定义 User、JsonConfig 两个模型，创建 FastAPI 应用，将 Admin 挂载到 /super，并通过 AuthenticationBackend 实现登录、登出和会话认证。配置示例还展示了 ModelView 的常用定制方式，包括中文列名、展示字段控制、插入和更新时拦截 password 字段并进行 MD5 加盐处理，以及 JSON 字段在后台页面中的录入注意点。适合正在为 FastAPI 内部系统、配置管理页面或轻量运维后台选型的开发者，用来快速判断 SQLAdmin 的适用范围，并参考其最小可运行集成方式。

Python 开发

2025年12月6日12 分钟

Python协程调度

这篇笔记聚焦 Python 中 asyncio 的协程调度机制，核心是说明单线程如何借助事件循环、协程、Future 和 Task 实现 I/O 密集任务的并发执行。正文从 async def、await、asyncio.run、async for、async with 等基础用法切入，解释协程在遇到 await 时会挂起当前执行、把控制权交还给事件循环，并在异步操作完成后被重新唤醒。示例重点对比了 create_task 后再顺序 await、直接 await 协程，以及使用 asyncio.gather 的差异：create_task 会立即把任务提交给事件循环并发启动，而 await task 只等待当前协程，不会阻塞其他已调度任务；直接 await 多个协程则会形成串行执行。文中还强调 asyncio.sleep 是非阻塞延时，只挂起当前任务，不占用线程资源。后半部分引入 threading 示例，说明线程由操作系统抢占式调度，多个线程共享进程内存但存在数据竞争风险，并在 CPython 中受到 GIL 限制，因此更适合 I/O 场景而非 CPU 密集计算。整体适合正在区分进程、线程、协程调度模型的 Python 后端或异步编程学习者，用来建立“协作式事件循环”和“抢占式系统线程”之间的基本判断框架。

Python 开发

2025年12月6日9 分钟

工厂基类的使用

这篇笔记聚焦一个用于 Python 本地函数管理的工具工厂基类，目标是把分散的工具函数集中注册、统一生成 OpenAI tool calling 可用的 tools 描述，并通过名称完成动态调用。示例中的 BaseTool 维护 registry 字典，使用 @BaseTool.register 类方法装饰器在函数定义阶段把函数名和函数对象写入注册表，因此 get_weather、get_time 这类函数不需要额外手工汇总。get_tools() 遍历已注册函数，借助 inspect.signature(fn) 读取参数签名，再组装出包含 type、function、description、parameters、required 等字段的 function schema，便于直接传给 OpenAI。call(name, args) 则根据工具名查找对应函数并用关键字参数执行，若名称未注册会抛出 ValueError，从而把调用入口收敛到一个方法中。文章还用“装饰器等价于 BaseTool.register(get_weather)”的展开方式解释了注册机制，帮助读者理解 registry.items() 中 name 与 fn 的来源。适合正在把 Python 函数接入 OpenAI tools、或想先掌握装饰器、注册表、函数签名提取三者协作方式的 AI 应用开发者参考。

Python 开发

2025年12月6日15 分钟

pytest测试代码专用

这份笔记围绕 Python 项目中的 pytest 测试代码编写展开，先从 pytest 的定位、安装方式、pytest.ini 中 testpaths 与 pythonpath 的基础配置讲起，再用 tests 目录下的最小 test_example 示例说明普通函数加 assert 的测试入口。内容整理了常见测试写法，包括任意 Python 表达式断言、pytest.mark.parametrize 参数化、fixture 复用数据准备与清理逻辑、pytest.raises 捕捉异常、用 class 组织测试，以及通过文件、类、方法路径或 -k 关键字精确运行用例。命令行部分覆盖 -v、-x、--maxfail 等常用参数，适合快速建立本地测试执行习惯。后半部分转向 FastAPI 路由测试，同步接口使用 fastapi.testclient.TestClient，异步接口则结合 pytest-asyncio、httpx.AsyncClient 与 ASGITransport，在内存中直接向 ASGI app 发请求，避免启动 uvicorn 和真实端口。文章特别提示 AsyncClient(app=...) 已弃用且可能引发 502、生命周期未触发或路由异常等问题，推荐显式使用 transport=ASGITransport(app=app)。整体更像一份面向后端开发者的 pytest 与 FastAPI 接口测试速查模板，读者可以据此搭建基础测试目录、编写常见用例，并理解 ASGITransport 在异步接口测试中的作用边界。