Xunsearch: Chinese Full-Text Search with PHP and Docker

Xunsearch targets Chinese search inside PHP applications

Xunsearch, also known as 迅搜, addresses the problem of adding full-text search when ordinary database queries are not enough. The README identifies MySQL database search, website and forum search, industry portals, vertical search, and document or literature retrieval as intended applications. Its primary audience is a developer who needs a dedicated search index and wants to integrate it through a programming package instead of designing every indexing and query component independently.

The search stack rests on two named foundations. Xapian provides the index design, while SCWS handles Chinese word segmentation. This combination addresses a core difference between Chinese and space-delimited text processing. Xunsearch places the backend index, search service, and SDK within one system. The README also says the front end and back end can be deployed on different servers, which permits the PHP application and native search service to have separate machines.

The documented feature set includes field search, result highlighting, field sorting, Boolean syntax, range retrieval, aggregation, related searches, weight adjustment, Pinyin search, and search suggestions. The compiled search system can run on Linux, FreeBSD, and other UNIX-like systems. The PHP SDK can run on any platform, including Windows, because the application connects to the service through sockets rather than loading the native backend into the PHP process.

This architecture has a clear audience but also a clear boundary. The currently documented SDK is for PHP. The README mentions that the socket-based interface could support other languages, but it explicitly says that only the PHP implementation is currently provided. A JavaScript, Go, Rust, or Python team should therefore not assume that an additional SDK is available. It would have to implement the undocumented non-PHP protocol itself or use another integration layer.

Xunsearch separates records, indexes, and PHP queries

The repository layout and README describe a service architecture rather than a library that scans application tables during each search request. Native source code is under src/, client packages are under sdk/, and README.arch is the designated architecture reference. This separation allows indexing and search requests to be served by a backend distinct from the machine running the PHP application.

An indexing workflow must first translate application records into fields that Xunsearch can store and query. Xapian supplies the index foundation, while SCWS supplies Chinese segmentation during text processing. The main README does not show a PHP schema-building call or a complete record-format example. Developers must consult sdk/php/README.md for the exact field definitions, data types, and SDK methods before constructing a production index.

At query time, the PHP SDK communicates with the search service through a socket. That mechanism explains the supported split deployment model, but it also creates an operational boundary between the PHP process and indexed content. Teams must account for backend availability, network routing, index consistency, and the process of applying database changes to the search index. The README lists useful query features, but it does not specify a synchronization strategy in the main project documentation.

The Dockerfile exposes ports 8383 and 8384. It also maps both ports to the container in its example command. The available project documentation does not assign a protocol or traffic type to either port, so an implementation should not expose both publicly without checking README.install, README.arch, or the installed service configuration. The README also does not document authentication, TLS, replication, or access controls for socket connections.

The container uses dumb-init as PID 1 through its entry point. This provides a defined process initialization and signal-forwarding path for the container runtime. The service still requires persistent storage and careful configuration. An indexed search deployment is not complete merely because the container starts successfully.

Xunsearch installation begins with README.install

The README does not include a complete manual installation command. It directs installation and upgrade work to README.install. The repository contains configure.ac, Makefile.am, compile, Dockerfile, Dockerfile.alpine, INSTALL, and other build-related entries, but their names do not establish a complete dependency list or prove that an unprepared operating system will build the project successfully.

The Dockerfile offers a more concrete installation route, although it does not pin the downloaded archive. Its build stage downloads xunsearch-full-latest.tar.bz2, extracts it, and invokes setup.sh with the prefix /usr/local/xunsearch:

RUN wget -qO - https://www.xunsearch.com/download/xunsearch-full-latest.tar.bz2 | tar -xj \
    && cd xunsearch-full-* && sh setup.sh --prefix=/usr/local/xunsearch \
    && cd .. && rm -rf xunsearch-full-*

This command performs the documented acquisition and setup steps, but `latest` does not identify an immutable archive version. The GitHub repository has no GitHub releases, so operators cannot infer a fixed release version from a GitHub release asset. A deployment built from this Dockerfile can change when the remote archive changes. Teams requiring repeatable builds should record the resulting Xunsearch version and retain the exact archive used for that installation.

The runtime container declares a persistent data directory and exposes two ports:

VOLUME /usr/local/xunsearch/data
WORKDIR /usr/local/xunsearch
EXPOSE 8383 8384

The volume directive keeps container-managed data within /usr/local/xunsearch/data when the host path is mounted. The README.install file should be consulted before starting the service because the main README does not describe initial configuration or first-run commands. The same applies to docker-entrypoint.sh, which may perform initialization not shown in the abbreviated Dockerfile.

A complete first-use example is not possible from the README and Dockerfile alone. Writing invented API calls would not help a reader. The first documented implementation step is to follow README.install, then use sdk/php/README.md to create the index schema, configure the SDK connection, load representative Chinese records, and issue a query using the methods defined there.

Xunsearch Docker deployment uses an older Ubuntu base

The Dockerfile documents a runnable container command for the xunsearch image. It creates a persistent host path, publishes both documented ports, and uses the `hightman/xunsearch:latest` tag:

docker run -d --name xunsearch -p 8383:8383 -p 8384:8384 \
  -v /data/xunsearch:/usr/local/xunsearch/data hightman/xunsearch:latest

This command is the repository's documented starting point, not a complete production configuration. It does not specify a service account, credential, TLS certificate, database connection, log destination, or network restriction. Port 8383 and port 8384 are both published to the host, but the project documentation does not explain their distinct roles. Operators must confirm the bindings from the installed configuration before placing them behind a public interface.

Both the build and runtime stages use `ubuntu:18.04`. That is a direct constraint for organizations that prohibit unsupported operating-system packages or require a newer container baseline. Dockerfile.alpine exists in the repository, but the Alpine path cannot be treated as a verified alternative. A team should inspect that file and confirm its base version, package dependencies, and startup behavior before selecting it.

The `latest` tag creates another reproducibility issue. The Dockerfile does not pin a digest, and the repository has no GitHub releases from which to select a versioned image. If the same command is run at different times, the image can differ. Recording the image digest is therefore necessary when the deployment has to be reproduced or audited.

The runtime stage removes build dependencies and selected development files. It deletes `/usr/local/xunsearch/include`, `/usr/local/xunsearch/sdk`, and `/usr/local/xunsearch/bin/xs-php`. This reduces the runtime layer, but an application should not assume that the backend image contains an SDK for local development. The PHP project needs its own documented SDK package.

Xunsearch licensing needs verification against COPYING

The repository metadata classifies the license as a custom license that GitHub cannot categorize, while the README says Xunsearch uses GPL. The README directs readers to the COPYING file for the conditions covering modification and redistribution. Because these descriptions are not identical, an engineer should examine COPYING rather than relying only on a repository badge or the README summary.

The README confirms that the source can be obtained under the stated license conditions. It does not provide a legal interpretation of those conditions, nor does it explain in detail whether generated SDK files or bundled components carry separate notices. Xapian and SCWS are named foundations of the system, and any separate licensing details for those components should be checked in the exact distribution being deployed.

The phrase `xunsearch-full-latest.tar.bz2` makes license and upgrade bookkeeping more involved. The Docker build retrieves an archive whose version is represented as `latest`, while the source repository contains ChangeLog, NEWS, and version-sh but no GitHub release. Before an organization approves a deployment, it should record which archive was downloaded, which PHP SDK and native backend files were installed, and which license notices accompanied those files.

The last push was on 2026-04-06, and the repository is not archived. That status does not establish a semantic-version release process or compatibility with current PHP and operating-system releases. Xunsearch also has no GitHub releases to serve as stable upgrade checkpoints. Upgrade planning therefore depends on README.install, the changelog, and the archive version rather than an ordinary GitHub release workflow.

Xunsearch trades infrastructure work for a ready search boundary

The closest architectural alternative is to use Xapian directly and build the surrounding indexing and PHP integration code. Xapian supplies the index layer, but a direct implementation must define the application schema, connect Chinese segmentation to indexing and queries, keep records synchronized with the source database, and expose search operations through application code. Xunsearch combines that infrastructure into a dedicated service and supplies a PHP SDK around it.

This is a useful trade-off for a PHP team that wants Chinese full-text search without assembling every layer itself. The cost is an additional native backend and a socket boundary between PHP and the search service. That boundary introduces deployment, monitoring, persistence, and network configuration concerns that do not exist when an application uses only its primary database.

Xunsearch is the wrong tool when a documented SDK is required for a language other than PHP. It is also a poor match for an organization that cannot accept Ubuntu 18.04 as a container base or cannot tolerate an installation recipe that uses `latest` without an immutable image reference. The README does not promise multi-node search, replication, snapshots, authentication, or rollback. Projects that require those features as documented guarantees need to verify them before adoption.

The README also describes a theoretical capacity of 4 billion records for one search library. That is a stated design claim, not a benchmark result or a guarantee for a particular hardware configuration. Evaluation should use representative Chinese records and the required field, highlighting, sorting, range, aggregation, and Pinyin behavior. No output or performance figures are provided in the README, so a production decision should rely on the application's own documented workload after confirming those query requirements against sdk/php/README.md.

Editorial conclusion

PHP developers who need a self-hosted Chinese search service and can operate a native C/C++ backend should evaluate Xunsearch. Projects requiring a documented non-PHP SDK, published GitHub releases, reproducible image versions, or a current container base should look elsewhere. Before adoption, verify README.install, sdk/php/README.md, docker-entrypoint.sh, the roles of ports 8383 and 8384, and the exact terms in COPYING.

Frequently asked questions

Official sources

1. hightman/xunsearch on GitHub
2. Issues
3. Project website
4. README