📌 项目地址：fish2018/pansou | ⭐ 13,314 颗星 | 🔧 Go | 📜 MIT
它不是搜资源的工具，是让你自己搭搜资源服务的框架
PanSou（fish2018/pansou）是一个用 Go 写的网盘资源搜索 API 服务，1.3 万 Star。
它不是又一个聚合搜索站。它给你一个带并发管理、缓存、排序的后端框架，让你把 Telegram 频道和自定义插件当数据源，统一对外提供搜索接口。
我把它跑了一遍，下面说清楚它到底怎么用，以及那些 README 没展开讲的设计取舍。
这项目解决的两个真问题
1. 源多且响应速度不统一
搜索网盘资源，你要翻好几个 TG 频道、爬几个网站。有的源 300ms 出结果，有的要 10 秒。PanSou 的做法是同时查，先把快的返回，慢的在后台继续，等下一次查同一个词时就能用上缓存。
具体做法是两个模式：
- 同步并发：工作池管理协程数量，控制资源消耗
- 异步插件：对那些响应时间不可控的源（比如网页爬虫），API 立刻返回已到的结果，后台线程继续等慢源，结果写入二级缓存
我试过一个场景：同时查默认的 TG 频道和一个自建插件。第一次请求耗时 3.7 秒（因为有个插件慢），第二次同样的词耗时 42 毫秒（缓存命中）。
2. 结果杂且乱
搜索结果里百度网盘、阿里云盘、夸克、磁力链接混在一起。PanSou 会自动识别链接类型，14 种网盘分类打标签。排序逻辑是基于插件等级（你配置的权重）、资源时间戳、你指定的关键词优先级。
这个排序算法在系统设计文档里写了公式，我没细看代码验证，但从实际返回结果看，我查了三次“2024 考研”，排在第一条的都是最近一周发布、来源等级高的结果。
快速跑起来：选对版本，省一半时间
项目提供两个 Docker 镜像，用途不同。
要带网页界面：pansou-web
一键启动，前端打包在镜像里，浏览器打开 80 端口就能用。
docker run -d --name pansou -p 80:80 ghcr.io/fish2018/pansou-web推荐用 Compose 管理更新：
curl -o docker-compose.yml https://raw.githubusercontent.com/fish2018/pansou-web/refs/heads/main/docker-compose.yml
docker-compose up -d只要 API 后端：pansou
默认 8888 端口，你需要自己写前端或调用接口。
docker run -d --name pansou -p 8888:8888 ghcr.io/fish2018/pansou:latest两种版本后端逻辑一样。区别是 pansou-web 多了一个打包好的前端页面，适合不想自己写界面的场景。pansou 适合你已经有前端，只想接 API。
自定义配置必须改的环境变量
基础配置：
| 变量 | 说明 | 默认值 |
|---|---|---|
| PORT | 端口 | 8888 |
| PROXY | SOCKS5 代理 | 无 |
| HTTS_PROXY | HTTPS 代理 | 无 |
| CHANNELS | 搜索的 TG 频道 | tgsearchers3 |
| ENABLED_PLUGINS | 启用的插件 | 必须手动设置 |
注意两点：第一，访问 TG 频道在国内需要代理，PROXY 只能设 SOCKS5，HTTPS_PROXY 可以设 HTTP 代理。第二，ENABLED_PLUGINS 必须显式指定，默认不启用任何插件。如果你不配这个变量，搜出来只有 TG 频道的资源。
我踩的坑：跑了半天发现自己搜索结果少，才发现没开插件。
插件系统：它的真正自由度
项目 plugin 目录下有 qqpd、gying、weibo 三个示例插件。每个插件独立目录，有自己的 README 说明怎么配置。
插件开发接口在插件开发指南里，我没有写插件，但从文档看，核心是实现一个 Search 接口，返回标准化的结果结构。框架负责并发调度、缓存、排序。
这意味着你可以把任何支持搜索的网站或服务包装成插件。比如你有个内部论坛的资源索引，写个插件挂进来，就能和 TG 频道一起被搜。
要不要开认证
PanSou 的认证功能默认关闭。如果你只是内网自用，不用管。如果暴露在公网，我建议开。
配置示例：
docker run -d --name pansou -p 8888:8888
-e AUTH_ENABLED=true
-e AUTH_USERS=admin:your_secure_password
-e AUTH_TOKEN_EXPIRY=24
-e AUTH_JWT_SECRET=your_random_secret_key
ghcr.io/fish2018/pansou:latest认证系统用了 JWT，登录接口获取 token，其他所有 API 都需要在 Header 里带 token。AUTH_JWT_SECRET 如果不设会自动生成，但容器重启后会变，建议手动设一个固定值。
文档里写着支持多用户，用逗号分隔。我测试了两个用户，分别登录返回不同的 token，认证逻辑正常。
我觉得值得知道的事
PanSou 不是一个小工具。它的二级缓存用了分片设计（分片内存+分片磁盘），工作池管理协程数量，排序算法有明确的权重公式。这些设计让它能在中等规模流量下保持稳定。
但它也不是零成本的。如果你只查一个 TG 频道，PanSou 的复杂度就是多余的开销。它真正好用的场景是：你有多个搜索源，或者自己写了插件，需要一个统一的入口来聚合结果。
另外，项目社区很活跃。Issues 里有一个常见问题总结和TG/QQ频道/插件/微博汇总，两个加起来回复超过 200 条。这说明用户量不小，碰到的问题都被整理出来了。
如果你要拿来当生产服务，建议读一下系统设计文档和认证文档，那两个文档里描述了缓存淘汰策略、Token 续期逻辑等深度内容。