Guide · Open source

How to use PanSou: Docker setup, API search and plugins

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

PanSou is an open-source search API that looks for cloud-drive share links across Telegram channels and custom plugins, then returns and sorts the results. This guide shows you how to start it with Docker, send a search request, and turn on the optional settings. By the end you will know how to run the service, query it and configure its main environment variables.

PanSoufish2018/pansou · ★ 15.1k · MIT Install options & downloads

Quick start

1Install Docker. Make sure Docker is installed and running on your machine.
2Start the container. Run the bundled front-end image on port 80, or the API-only image on port 8888.
3Open the service. Visit the port you mapped. For the API-only version, the README lists http://localhost:8888.
4Set channels and plugins. Use CHANNELS and ENABLED_PLUGINS to choose sources. Plugins must be listed explicitly.
5Add a proxy if needed. If Telegram is blocked, set PROXY to a SOCKS5 address or set HTTP_PROXY and HTTPS_PROXY.
6Send a search request. POST a JSON body with the keyword in kw to /api/search.

What PanSou does and who it is for

PanSou is a search service for cloud-drive resource links, such as Baidu, Aliyun, Quark and 115 drives. It searches Telegram channels and plugins at the same time, sorts the results and groups them by drive type. It is offered as a web API, and the README describes a bundled front end in Docker.

The project is for study and research only, and the description says it must not be used for profit. It must be deployed and configured by you, so it is a fit for developers and people comfortable with Docker or Go.

Good fit: developers who want a self-hosted search API for cloud-drive share links
Good fit: people who can configure a SOCKS5 or HTTP proxy if Telegram is restricted where they live
Not a fit: commercial projects, since profit-making use is prohibited

Install PanSou with Docker

You need Docker installed. The README offers two images: a front-end and back-end bundled version, and a back-end API only version. Both start with a single command.

For the bundled version, the README says the command starts the service with no extra setup. The API-only version listens on port 8888.

Bundled front end and back end: the web interface is served on port 80
API only: the API is served on port 8888

docker run -d --name pansou -p 80:80 ghcr.io/fish2018/pansou-web

docker run -d --name pansou -p 8888:8888 ghcr.io/fish2018/pansou:latest

Run PanSou with Docker Compose

The README recommends Docker Compose. Download the compose file for the version you want, then start it in the background and check the logs. The API-only version also lists http://localhost:8888 as the address to visit once it is running.

# Download the config file
curl -o docker-compose.yml https://raw.githubusercontent.com/fish2018/pansou/refs/heads/main/docker-compose.yml

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

Search with the API

Send a POST request to /api/search with a JSON body that contains the keyword in the field kw. The README example uses a Chinese film title as the keyword. When authentication is off, you do not need a token.

If you enable authentication, every API call except login and health checks needs an Authorization header with a Bearer token.

Endpoint: POST /api/search
Body field for the keyword: kw
Login endpoint: POST /api/auth/login

curl -X POST http://localhost:8888/api/search \
  -H "Content-Type: application/json" \
  -d '{"kw":"速度与激情"}'

Configure channels, plugins and proxy

Set environment variables to control where PanSou searches. CHANNELS sets the default Telegram channels, separated by commas, and its default is tgsearchers7. ENABLED_PLUGINS takes a comma-separated list of plugins, and the README says plugins must be enabled explicitly; it has no default value.

If Telegram is blocked where you are, set PROXY to a SOCKS5 address, or set HTTP_PROXY and HTTPS_PROXY. The README gives the example socks5://127.0.0.1:1080.

PORT: service port, default 8888
PROXY: SOCKS5 proxy, none by default
CHANNELS: default Telegram channels, default tgsearchers7
ENABLED_PLUGINS: plugins to enable, none by default
AUTH_ENABLED: turns on authentication, default false

docker run -d --name pansou -p 8888:8888 \
  -e PROXY=socks5://127.0.0.1:1080 \
  -e ENABLED_PLUGINS=labi,zhizhen \
  ghcr.io/fish2018/pansou:latest

Turn on authentication (optional)

Authentication is off by default. Set AUTH_ENABLED to true and list users in AUTH_USERS as user:password pairs. Token expiry is set in hours with AUTH_TOKEN_EXPIRY, which defaults to 24. The README advises setting AUTH_JWT_SECRET yourself, because otherwise it is generated automatically.

AUTH_USERS format: user1:pass1,user2:pass2
AUTH_TOKEN_EXPIRY default: 24 hours
AUTH_JWT_SECRET: set this yourself, the README recommends it

curl -X POST http://localhost:8888/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Build from source (advanced)

The README lists Go 1.18 or later as the requirement for building from source. Clone the repository, build a static Linux binary with the command below, then run the binary. The README also documents many advanced settings, such as CACHE_TTL and PLUGIN_TIMEOUT, and says the defaults are usually fine.

Requirement: Go 1.18+
Advanced settings are listed in the README under an expandable section and generally do not need changing

git clone https://github.com/fish2018/pansou.git
cd pansou
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -extldflags '-static'" -o pansou .
./pansou

What people use it for

Run a private API that returns cloud-drive share links for a keyword
Add your own search plugin to bring in another source, as described in the plugin development guide
Limit access to a self-hosted instance with AUTH_ENABLED and per-user passwords
Place the API behind nginx with rate limiting, as the README's nginx example shows

Frequently asked questions

Is PanSou free to use?

The source is MIT licensed, but the project description says it is for study and research only and must not be used in any form for profit. Commercial use is therefore excluded by the project's own notice. Read the licence and that notice before you deploy it.

What do I need to install PanSou?

The README lists Docker as the install method, so Docker is the main requirement. Building from source needs Go 1.18 or later. A SOCKS5 or HTTP proxy is optional and only needed if Telegram is blocked where you are.

How do I install PanSou with Docker?

Run docker run -d --name pansou -p 8888:8888 ghcr.io/fish2018/pansou:latest for the API only, or use the pansou-web image on port 80 for the front end bundled version. Both are listed in the README.

Why are my search results empty?

The README does not give a troubleshooting list. Check that ENABLED_PLUGINS and CHANNELS are set, since plugins must be enabled explicitly and the default channel is tgsearchers7. If Telegram is blocked in your region, configure PROXY and check the logs with docker logs or docker-compose logs -f.

Is there an alternative to PanSou?

The source does not name comparable projects, so this guide cannot compare PanSou with others. Judge it by your own needs, such as whether you need a self-hosted API, plugin support and Telegram channel search.

Does PanSou guarantee legal content?

No. The README does not address content sources or legality beyond the study-use notice, so it does not promise legal or guaranteed results. Check the rules that apply where you live before you use any results.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PanSou suits developers and technically confident users who want a self-hosted search API for cloud-drive share links and are willing to configure Docker and a proxy. It is a poor choice for anyone who wants a hosted service, a commercial product, or a source with guaranteed legal content.

Install options & downloads