这份笔记围绕 PicGo + GitHub 搭建免费图床展开，目标是把 GitHub 公开仓库作为图片存储位置，并由 PicGo 自动完成上传、生成链接和复制到剪贴板。内容从创建 image-hosting 之类的公开仓库开始，记录了初始化 README、生成 classic Personal Access Token、仅勾选 repo 权限、保存 token 等准备步骤，并补充了 macOS 安装 PicGo 时遇到“已损坏”提示可用 xattr 或 spctl 命令处理。配置部分重点说明 GitHub 图床需要填写 token、username/repo 格式的仓库名、main 或 master 分支、可选存储路径，以及 raw URL、GitHub Pages 域名或 jsDelivr CDN 域名等访问方式。上传流程覆盖快捷键、拖拽和手动选择文件，生成的链接可按 Markdown、HTML 或 URL 格式用于博客和 Markdown 文档。后半部分进一步解释 GitHub Pages 的用户站点与项目站点差异：免费账户通常只能有一个 username.github.io 用户站点，但可基于多个公开仓库创建项目站点，Pro 账户则可在私有仓库启用 Pages。文中也提醒仓库和 Pages 站点建议控制在 1GB 内，单文件不超过 100MB，图片公开可访问且 token 不能泄露，适合需要低成本托管博客图片并理解链接形式、访问速度与公开性边界的个人开发者。

开发工具

2025年12月6日1 分钟

关于“开发工具使用”类别

“开发工具使用”类别用于承载与开发工具相关的说明性内容，并为后续文章归档提供一套可判断的分类准则。它关注的重点不是单个工具的零散记录，而是说明为什么需要这个类别、它承担什么用途，以及哪些内容应被归入其中。该类别需要明确自身与既有分类的边界，避免与更偏向编程语言、框架实践、环境配置或问题排查的栏目发生重复。适合纳入的内容通常包括工具使用经验、功能说明、工作流整理、选型依据、常见操作规范，以及围绕开发效率展开的实践记录。正文同时提示应评估该类别是否有独立存在的必要，必要时也可以考虑与相近类别或子类别合并。对维护知识库或技术博客分类体系的读者来说，这类说明的价值在于帮助统一归档标准，减少后续发布文章时的分类歧义。

服务器与部署

2025年12月6日2 分钟

picgo配置cloudflare-r2

这篇记录聚焦于用 PicGo 搭配 Cloudflare R2 搭建博客图床，并通过 Cloudflare 缓存规则改善图片访问速度。配置部分选择的是 wayjam 维护的 picgo-plugin-s3，而不是泛泛说明 S3 协议本身，核心操作是在 PicGo 插件市场安装对应版本后，按 R2/S3 存储参数完成上传配置。文章特别强调上传路径的命名方式，示例为 blog/img/{year}/{month}/{md5}-{timestamp}.{extName}，利用年份、月份、MD5、时间戳和扩展名组合，让对象路径尽量唯一，避免后续缓存命中与文件更新之间产生混淆。完成上传路径后，还需要设置 PicGo 的输出 URL，使上传后的图片能按自定义 CDN 域名路径被博客引用。后半部分转向 Cloudflare 后台的 Cache TTL 自定义规则，因为文件数量增多时每次加载可能变慢，作者通过匹配访问路径并设置缓存时间，让首次访问之后的图片加载更快。整体适合已经具备 PicGo、Cloudflare 域名和 R2 存储基础的用户参考，重点价值在于串起上传、URL 输出和边缘缓存三段链路，而不是从零解释 R2 或 S3 的所有概念。

服务器与部署

2025年12月6日6 分钟

minio配置

这份笔记面向 MinIO 对象存储的初始配置与公开读取场景，重点把控制台操作和 S3 客户端接入参数对应起来。创建本地用户时，user_name 可作为 MINIO_ACCESS_KEY，password 可作为 MINIO_SECRET_KEY，MINIO_ENDPOINT_URL 通常填写反向代理后的对象存储地址；如果直接用 IP 访问，则需要带上 9000 端口，区域在无特殊配置时可使用 auto。权限体系部分区分了 Users、Groups、OpenID 和 LDAP：本地用户适合直接分配 IAM policy，组用于批量继承权限，OpenID 适合接入 Keycloak、Auth0 等身份提供商实现 SSO，LDAP/AD 则便于复用企业账号和组映射。桶配置部分解释了 Custom Access Policy、服务器端加密、跨集群复制、对象锁、标签和配额等开关的含义，帮助判断哪些能力只是当前禁用，哪些需要按合规、同步或容量管理需求启用。公开文件读取策略示例只允许 GetBucketLocation 和 GetObject，并将对象资源限定在 public 桶下，同时明确不放行 ListBucket，避免匿名用户枚举桶内对象列表。适合正在把 MinIO 作为 S3 兼容存储接入应用、需要配置访问密钥、桶策略和基础权限边界的开发或运维人员参考。

服务器与部署

2025年12月6日8 分钟

给ip地址生成CA证书

这份配置记录面向没有域名、又希望在国内服务器上以 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 后端或异步编程学习者，用来建立“协作式事件循环”和“抢占式系统线程”之间的基本判断框架。

文章归档

183 篇