PanSou: A Go-Based Search API for Chinese Cloud Storage Resources

What PanSou Does and Who It Is Built For

Chinese cloud storage services fragment their content across many Telegram channels, and manually searching each channel is slow. PanSou is a self-hosted search API service that queries multiple Telegram channels and third-party plugins at the same time and returns a unified list of results, sorted by relevance and recency, through a REST endpoint.

The README describes the target use as learning and research, and explicitly prohibits commercial use in any form. PanSou is a developer tool: it exposes a JSON API rather than a finished consumer application, though a Docker image combining the frontend and backend is provided for easier evaluation. The intended operator is someone building a personal tool for their own use, not a team running a public service.

The service handles links for Baidu cloud storage (baidu), Alibaba Drive (aliyun), Quark cloud (quark), Guangya Drive (guangya), Tianyi cloud (tianyi), UC cloud (uc), mobile cloud (mobile), 115 (115), PikPak (pikpak), Xunlei (xunlei), 123 Pan (123), magnet links, and ed2k links. Results that do not match any of these categories are classified as others.

Concurrent Channel and Plugin Search Architecture

PanSou queries multiple Telegram channels concurrently using a worker pool. The README describes a sharded memory and sharded disk cache built on bbolt that stores results from repeated queries, significantly reducing latency on duplicate searches. The CHANNELS environment variable holds a comma-separated list of Telegram channel names to search by default; the docker-compose.yml in the repository ships with over a hundred pre-configured channel names.

The plugin system extends the search sources beyond Telegram channels. Plugins must be explicitly enabled by setting the ENABLED_PLUGINS environment variable to a comma-separated list of plugin names. The README describes an asynchronous plugin mode: when a plugin takes too long to respond, PanSou can return partial results immediately and continue processing in the background, adding results as they arrive. This approach addresses the problem of certain search sources that have long response times without blocking the entire response.

Sorting applies a multi-dimensional algorithm based on plugin level, recency of the result, and priority keywords. The service assigns a higher rank to plugins configured with a higher level, and more recent results appear above older ones within the same level.

The CONCURRENCY environment variable controls how many parallel searches run at once. The default is calculated automatically based on the number of configured channels and plugins.

Deploying PanSou with Docker

PanSou offers two Docker images. The backend-only API image runs on port 8888:

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

After the container starts, the API is accessible at http://localhost:8888. The docker-compose.yml in the repository includes a pre-populated CHANNELS list with dozens of Telegram channels and a full ENABLED_PLUGINS list covering around 50 plugins. Using the compose file instead of a bare docker run command is the practical starting point for a production-like deployment.

The frontend plus backend integrated image runs on port 80 and combines the web interface with the API in a single container. The README also notes that supervisor and nginx configuration examples are available in the repository for deployments that need more control over process management and reverse proxy setup.

Plugin documentation is maintained per-plugin in subdirectories under plugin/: qqpd, gying, weibo, and woniu each have their own README files documenting how to configure that specific plugin.

Authentication and Access Control

Authentication is disabled by default. When enabled via AUTH_ENABLED=true, all API endpoints except the login and health check require a valid JWT token. The token is obtained by POSTing to /api/auth/login with a JSON body containing the username and password. The response includes the token, an expiry timestamp, and the username.

To run the backend with authentication enabled for a single user:

docker run -d --name pansou -p 8888:8888 \
  -e AUTH_ENABLED=true \
  -e AUTH_USERS=admin:admin123 \
  -e AUTH_TOKEN_EXPIRY=24 \
  ghcr.io/fish2018/pansou:latest

The AUTH_USERS variable takes a comma-separated list in the format user1:pass1,user2:pass2, allowing multiple accounts. AUTH_TOKEN_EXPIRY sets the token lifetime in hours, defaulting to 24. The AUTH_JWT_SECRET variable sets the signing key; the README recommends setting it manually rather than relying on the auto-generated default.

With a token in hand, subsequent requests include it as Authorization: Bearer followed by the token string. The /api/auth/logout endpoint handles logout from the client side by instructing the client to delete the token; the server does not maintain a session.

Building from Source and Key Configuration Variables

The source build requires Go 1.18 or later. Cloning and building follows the standard Go pattern:

git clone https://github.com/fish2018/pansou.git
cd pansou

The README gives the production build command as a statically linked binary:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -extldflags '-static'" -o pansou .

Beyond CHANNELS, ENABLED_PLUGINS, and the authentication variables, a set of tuning variables control the cache and async behavior. CACHE_TTL sets how long cached results remain valid in minutes, defaulting to 60. CACHE_MAX_SIZE caps the cache at a size in megabytes, defaulting to 100. PLUGIN_TIMEOUT controls how long the service waits for a plugin before timing out, in seconds. PROXY accepts a SOCKS5 proxy URL such as socks5://127.0.0.1:1080 for environments where direct access to Telegram is restricted. ASYNC_RESPONSE_TIMEOUT determines how quickly PanSou returns a partial response when using the asynchronous plugin mode, defaulting to 4 seconds.

Where PanSou Falls Short and the Legal Disclaimer

PanSou is scoped to Chinese cloud storage platforms and Telegram channels. It does not cover Google Drive, Dropbox, OneDrive, or any Western storage service, and adding support for those would require writing new plugins from scratch. The plugin development guide and an AI-assisted plugin development skill file are available in the docs/ directory for developers who want to extend the plugin system, but the default channel list and plugin set are oriented entirely toward Chinese-language content.

The README states explicitly: this project is for learning and research only and must not be used in any form for profit. This is not a MIT licence carve-out but a separate disclaimer. The MIT licence permits broad reuse, but the README's explicit prohibition on commercial use is a constraint the operator accepts when deploying the service.

The asynchronous plugin system introduces one operational complexity: the ASYNC_MAX_BACKGROUND_WORKERS and ASYNC_MAX_BACKGROUND_TASKS variables need tuning on low-resource machines, because the defaults are calculated as multiples of the CPU core count and can exhaust memory on a small VPS.

Telegram's Native Channel Search as a Simpler Baseline

Telegram's built-in search lets a user search for messages inside any channel they follow. It is the direct baseline against which PanSou competes. The practical limitation of the native search is that it operates on one channel at a time, and finding a resource shared across many channels requires searching each separately.

PanSou's value proposition is precisely that aggregation: it queries dozens or hundreds of channels in a single API call and returns deduplicated, sorted results. For a developer who only follows two or three channels and searches them infrequently, the operational overhead of running a Docker container and maintaining a plugin list makes PanSou a heavier investment than simply using Telegram's interface.

For someone running automated searches, building a secondary interface, or needing programmatic access to cloud storage links at scale, the REST API is the distinguishing capability. Telegram does not offer a public API for channel search that returns structured link data; PanSou fills that gap with the constraint that it depends on non-official channel scraping, which is why the research disclaimer applies.

Repository Status and MIT Licence

The last push to this repository was on 2026-09-15. The repository is not archived.

The licence is MIT, as stated in the LICENSE file. The MIT licence permits use, modification, and distribution with attribution. The separate learning-and-research-only disclaimer in the README is not part of the licence text itself but is a usage condition that the author has attached to the project description. The go.mod file records a module path of pansou and a Go version of 1.25.0, indicating that the development environment uses a recent Go toolchain, though the README documents Go 1.18 as the minimum requirement for a source build.

Editorial conclusion

Developers building personal tools to search Chinese cloud storage resources across multiple Telegram channels can deploy PanSou with a single Docker command and query the API with a POST request to /api/search. The project's README explicitly states it is for learning and research only and must not be used for commercial purposes: any deployment should be read against the MIT licence and that disclaimer. Developers who need to search non-Chinese cloud storage services, or who need a single-channel solution without API overhead, will find PanSou's design too narrowly scoped for their use case.

Frequently asked questions

Official sources

1. fish2018/pansou on GitHub
2. Issues
3. License: MIT
4. Project website
5. README