# dubbo-go-pixiu: an Apache gateway that puts Dubbo clusters behind HTTP, gRPC, and LLMs

> Pixiu is a Go API gateway built on Dubbo-go, originally a proxy that let external protocols call internal Dubbo clusters and now positioned as a universal AI gateway that fronts LLMs and MCP servers, with a plugin framework, an admin UI, and a Kubernetes ingress controller mode.

**apache/dubbo-go-pixiu** — Based on the proxy gateway service of dubbo-go, it solves the problem that the external protocol calls the internal Dubbo cluster. At present, it supports HTTP and gRPC[developing].

- Repository: https://github.com/apache/dubbo-go-pixiu
- Website: https://dubbogo.github.io/dubbo-go-proxy/
- Stars: 565 · Forks: 193
- Language: Go
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-dubbo-go-pixiu

## The original job was protocol translation into Dubbo clusters

The repository description is the clearest statement of the original purpose: it is based on the proxy gateway service of dubbo-go and solves the problem that the external protocol calls the internal Dubbo cluster. The README's own framing has grown beyond that, calling Pixiu a next-generation AI and API gateway built on Dubbo-go that bridges external protocols with internal Dubbo clusters, supporting HTTP, gRPC, Dubbo2, and Triple. The protocol feature table says the same thing: proxying and translation between HTTP, gRPC, Dubbo2, and Triple protocols, delivering rich protocol gateway features. The user who benefits is a team with Java or Go microservices registered in Zookeeper or Nacos that now needs to be reachable from clients that speak HTTP. The repository topics list dubbo-cluster, dubbo-go, microservice, protocols, and http-proxies, which is the same story in keyword form.

## The AI gateway framing is the current positioning

The README marks two new capabilities with emphasis. The first is the evolution into a universal AI gateway, designed to simplify and unify access to LLMs and AI service providers, whether from public vendors or self-hosted models. The listed capabilities include unified access so you can connect to OpenAI, Anthropic, or any custom or on-prem LLM or MCP service through a single API gateway layer, and MCP Server exposure, which lets you expose existing HTTP APIs and backend services as MCP servers so AI applications can invoke business logic directly. The second new capability is the Kubernetes Ingress Controller, which applies the gateway abilities at the cluster ingress layer through declarative routing. The dependency list backs the MCP claim, since `github.com/mark3labs/mcp-go` is a direct requirement, along with `github.com/open-policy-agent/opa` for policy.

## A plugin and filter framework is where the work happens

The extension story is described in the Why section as a powerful plugin and filter framework that makes it easy to extend or customise gateway behaviour, from routing and authentication to observability and AI-specific use cases. The README's AI feature list spells out what rides on top of it: authentication, caching, rate-limiting, retry policy, observability, and even model orchestration, all through the plugin system, plus fine-grained cost control, auditing, and token accounting for large-scale AI deployments. The supporting table adds the conventional gateway concerns. HTTPS, JWT, and OAuth2 for security, service discovery through Zookeeper or Nacos, rate limiting, circuit breaking, and traffic shaping via Sentinel, OpenTelemetry and Jaeger for tracing, metrics, and logging, and a Pixiu-admin UI for real-time visual configuration of gateway rules and policies. The admin directory at the repository root is that control plane.

## Running the gateway locally is a Docker build and a container run

The README's deployment section is the practical part. You build the image from the root directory where the Dockerfile lives:

```shell
# You can customize the image name and tag, here we use dubbo-go-pixiu:local
docker build -t dubbo-go-pixiu:local .
```

Then you start a container with the default configuration:

```shell
docker run --name pixiu-gateway -p 8888:8888 -d dubbo-go-pixiu:local
```

If you need your own configuration, you mount your files over the container's `/etc/pixiu/` directory, which is where the image copies its `configs` tree and creates the directory in the Dockerfile. The mount flags point at a local `conf.yaml` and a local `log.yml`, and the container still runs the image you built locally, so the image name has to match what you tagged. The port 8888 is the one to remember, and the config file names are `conf.yaml` and `log.yml`.

## The admin control plane needs etcd, OPA, and MySQL

The Pixiu-admin UI is managed through a Docker Compose stack rather than the gateway image alone. For a single-instance development deployment you start it without a key using `docker compose up -d`, and the README notes that when `DUBBOGO_PIXIU_JWT_SIGN_KEY` is empty the admin generates a random key, while the `.env.example` file shows the same variable and says to set a persistent key with `openssl rand -hex 32`. The compose file lists the services the admin needs: an etcd service from `quay.io/coreos/etcd:v3.6.1` with authentication allowed and a data volume, an OPA service from `openpolicyagent/opa:1.13.1` listening on 8181, and a MySQL 8 service with a `pixiu` database and `pixiu_user` credentials. That is a substantial stack to run before you touch a gateway rule, and it is the price of the visual management plane.

## The build pulls in a WebAssembly plugin runtime

The Dockerfile explains an unusual build requirement. The builder stage is `golang:1.25.4-bookworm` and it installs gcc, because `CGO_ENABLED=1` is set, and the build command carries the `wasmer` build tag with a `go build` that uses the `-tags` option, the `-trimpath` flag and linker flags for stripping symbols. The comment in the file explains that the wasmer tag remains because the wasmer plugin needs to be built, and that if the wasm feature is removed in the future, the tag and the wasm related commands can go. The build then locates the shared library and copies it into the image, and the final stage is `oowy/glibc:2.39-alpine3.20` with a nonroot user. The practical implication is that a Pixiu container is not a small static binary. It carries a CGO dependency and a native library, which affects image size and the platforms you can build for.

## Where dubbo-go-pixiu is the wrong tool

The limits come from the same place the strengths do. The first is ecosystem. The dependency list is dominated by Dubbo and Spring Cloud integration, with the Dubbo-go runtime, the Hessian2 codec, the Triple protocol, the Zookeeper client, and both Nacos SDKs, and if your services are not in that world the gateway is bringing a large amount of machinery for a general HTTP proxying job. The second is scope. This is now three products in one repository, an API gateway, an AI gateway, and a Kubernetes ingress controller, with an admin UI, a plugin system, and an OPA integration, and a team that wants one of those is adopting all of it. The third is release cadence, since the listed releases are v1.1.0 from 2026-01-04 after v1.0.0-rc4 in April 2024, and the default branch is `develop` rather than a release branch, so the code you read on the default branch is ahead of the last tag.

## Conclusion

dubbo-go-pixiu fits a team running Dubbo or Spring Cloud services that wants external callers, whether HTTP, gRPC, or an LLM client, to reach them through one gateway with authentication, rate limiting, and tracing applied consistently. It is the wrong choice if your services are not in the Dubbo ecosystem, since the Dubbo integration is the core of the design, and it is the wrong choice if you want a small, focused gateway, because the AI gateway positioning, the ingress controller, the admin UI, and the plugin system are all present in the same project. Before you adopt it, run the Docker deployment below and look at the admin UI, and read the plugin framework docs, since that is where the real extension work will happen.

## FAQ

### What protocols can dubbo-go-pixiu proxy?

The README lists proxying and translation between HTTP, gRPC, Dubbo2, and Triple protocols, and the project description says it supports HTTP and gRPC, with gRPC marked as in development. The repository topics also list kafka, rocketmq, and grpc-go among the related technologies.

### How do I run dubbo-go-pixiu with Docker?

Build the image from the directory containing the Dockerfile with `docker build -t dubbo-go-pixiu:local .`, then run `docker run --name pixiu-gateway -p 8888:8888 -d dubbo-go-pixiu:local`. To use your own configuration, mount your `conf.yaml` and `log.yml` into the container's `/etc/pixiu/` directory.

### What does the Pixiu AI gateway mode actually do?

It provides unified access to LLMs and AI service providers, whether public vendors or self-hosted models, so you can connect to OpenAI, Anthropic, or a custom or on-prem LLM or MCP service through one gateway layer. It also lets you expose existing HTTP APIs and backend services as MCP servers, and applies authentication, caching, rate limiting, retry policy, observability, and model orchestration through its plugin system.

### What services does the Pixiu admin UI need?

The docker-compose.yml in the repository lists etcd, an OPA service on port 8181, and a MySQL 8 service holding a `pixiu` database. The README says a single-instance development deployment can be started with `docker compose up -d`, and that when `DUBBOGO_PIXIU_JWT_SIGN_KEY` is empty the admin generates a random key.

### How does dubbo-go-pixiu handle service discovery and traffic governance?

Service discovery integrates with Zookeeper, Nacos, or any service registry to discover Dubbo and Spring Cloud services automatically. Traffic governance integrates with Sentinel for fine-grained rate limiting, circuit breaking, and traffic shaping, and observability comes from OpenTelemetry and Jaeger support for tracing, metrics, and logging.

## Sources

- [apache/dubbo-go-pixiu on GitHub](https://github.com/apache/dubbo-go-pixiu)
- [License: Apache-2.0](https://github.com/apache/dubbo-go-pixiu/blob/develop/LICENSE)
- [Project website](https://dubbogo.github.io/dubbo-go-proxy/)
- [README](https://github.com/apache/dubbo-go-pixiu/blob/develop/README.md)
- [Releases](https://github.com/apache/dubbo-go-pixiu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-dubbo-go-pixiu