# r-nacos: A Rust Nacos Server for Configuration and Discovery

> r-nacos re-implements the Nacos server in Rust while retaining compatibility with Nacos client SDK protocols. It suits development, testing, and selected production deployments that want Nacos features without a JDK-based server runtime.

**nacos-group/r-nacos** — Nacos server re-implemented in Rust.

- Repository: https://github.com/nacos-group/r-nacos
- Website: https://r-nacos.github.io/docs/
- Stars: 1,603 · Forks: 144
- Language: Rust
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nacos-group-r-nacos

## Why r-nacos Replaces the Java Nacos Server

r-nacos addresses a specific replacement problem: an application uses Nacos client SDKs for configuration management or service discovery, but the organization wants to operate a Nacos-compatible server without the Java-based distribution. The README says the implementation is compatible with current Nacos client-facing protocols, including Nacos 1.x HTTP OpenAPI and Nacos 2.x gRPC. That distinction matters because compatibility is defined at the SDK protocol boundary rather than by presenting r-nacos as a generic registry or configuration store.

The intended users are development teams that want Nacos in test environments, operators of small personal cloud deployments, and teams considering a non-customized Nacos service replacement. The README also describes a web management console and MCP support, including an embedded MCP server, interface forwarding, and conversion of registered ordinary HTTP interfaces into MCP services.

r-nacos does not remove the need to understand Nacos. Services still need compatible client-side configuration, and an HTTP port alone may not be sufficient for Nacos 2.x clients because the project also exposes a gRPC listener. The default gRPC port is the HTTP port plus 1000. This makes r-nacos a protocol-compatible server candidate, not an independent Rust SDK or client library.

## Protocol and Runtime Structure of r-nacos

The repository layout points to a server binary at `src/main.rs`, protocol definitions under `proto/`, client examples under `sdk-examples/`, cluster testing through `test_cluster.sh`, and integration tests under `integration_tests/`. Dependencies in `Cargo.toml` show an Actix Web HTTP layer, Tokio for asynchronous execution, Tonic for gRPC, SQLite through `rusqlite`, Serde for serialization, and an optional `mimalloc` allocator. These are repository facts rather than measured conclusions.

The documented network surface consists of an HTTP listener for Nacos HTTP OpenAPI and console traffic, a gRPC listener for Nacos 2.x protocol communication, and a separate console port. The defaults are `RNACOS_HTTP_PORT=8848`, gRPC on the HTTP port plus 1000, and `RNACOS_HTTP_CONSOLE_PORT=10848`. The Docker instructions publish all three ports as `8848`, `9848`, and `10848`.

Configuration and service state are persisted locally. `RNACOS_DATA_DIR` identifies the local database directory, with platform-dependent defaults documented in the startup table. Multi-node operation uses Raft-related settings such as `RNACOS_RAFT_NODE_ID`, `RNACOS_RAFT_NODE_ADDR`, `RNACOS_RAFT_AUTO_INIT`, and `RNACOS_RAFT_JOIN_ADDR`. Cluster communication can use `RNACOS_CLUSTER_TOKEN`. The README does not provide enough implementation detail to claim particular consensus timing, replication guarantees, or recovery behavior, so those points require validation in the project's own cluster tests and documentation.

## Quick Start with Cargo and Docker

For a Rust installation with Cargo already available, the README gives this as the shortest package-based first run. It installs the `rnacos` package and starts the resulting binary.

```bash
cargo install rnacos
rnacos
```

The source build path is also documented. Clone the repository, create a release build, and run the compiled application through Cargo.

```bash
git clone https://github.com/r-nacos/r-nacos.git
cd r-nacos
cargo build --release
cargo run --release
```

For Docker, pull the current formal image and start a named container with the documented HTTP, gRPC, and console port mappings.

```bash
docker pull qingpan/rnacos:stable
docker run --name mynacos -p 8848:8848 -p 9848:9848 -p 10848:10848 -d qingpan/rnacos:stable
```

The container works from `/io` and reads and writes configuration files there. The Compose example persists the container data directory and initializes the administrator credentials through environment variables.

```yaml
version: '3.8'

services:
  nacos:
    image: qingpan/rnacos:stable
    container_name: nacos
    ports:
      - "8848:8848"
      - "9848:9848"
      - "10848:10848"
    volumes:
      - ./data:/io:rw
    environment:
      - RNACOS_INIT_ADMIN_USERNAME=admin
      - RNACOS_INIT_ADMIN_PASSWORD=admin
      - RNACOS_HTTP_PORT=8848
    restart: always
```

A first practical check is to confirm that the process starts and that ports `8848`, `9848`, and `10848` are listening. The README does not define a health-check URL or a smoke-test command, so neither should be invented.

## Binary, Package Manager, and Kubernetes Installation Paths

The release packages target Linux, macOS, and Windows. On Linux or macOS, the documented archive example is named `rnacos-x86_64-apple-darwin.tar.gz`; users must select the release archive that actually matches their operating system and processor rather than copying that example blindly. After extraction, the command is simply `./rnacos`. On Windows, the README directs users to run `rnacos.exe`.

Homebrew is supported through a project tap, and the documented update path uses `brew upgrade r-nacos`.

```shell
brew tap r-nacos/r-nacos
brew install r-nacos
rnacos
```

Debian and Ubuntu packages are published through a community-maintained apt repository for `amd64` and `arm64`. Importing the signed repository key and adding the source installs the package.

```shell
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://r-nacos.github.io/r-nacos-apt/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/rnacos.gpg
echo "deb [signed-by=/etc/apt/keyrings/rnacos.gpg] https://r-nacos.github.io/r-nacos-apt stable main" | sudo tee /etc/apt/sources.list.d/rnacos.list
sudo apt update
sudo apt install rnacos
```

Kubernetes deployment is provided as a Helm chart. The README's basic commands add the chart repository and install the release under the name `r-nacos`.

```shell
helm repo add rnacos https://r-nacos.github.io/helm
helm install r-nacos rnacos/r-nacos
```

These paths cover local binaries, source builds, Linux package managers, Docker, and Kubernetes. They do not mean every distribution uses identical persistence, initialization, or upgrade behavior. In particular, Docker uses `/io`, while the local binary uses the platform-dependent `RNACOS_DATA_DIR` default.

## Configuration, Security, and Cluster Boundaries

The startup table exposes a large configuration surface, but several defaults deserve attention before r-nacos handles real data. `RNACOS_ENABLE_NO_AUTH_CONSOLE` defaults to `false`, while `RNACOS_ENABLE_OPEN_API_AUTH` also defaults to `false`. The latter is specifically documented as something not to enable during a transition from Nacos to r-nacos. Open API authentication validity is controlled by `RNACOS_API_LOGIN_TIMEOUT`, whose default is 3600 seconds.

The console limits repeated login failures. `RNACOS_CONSOLE_LOGIN_ONE_HOUR_LIMIT` defaults to five, and the table states that five consecutive failures lock an account for one hour. Administrator initialization values are applied only when the primary node starts for the first time. Changing `RNACOS_INIT_ADMIN_USERNAME` or `RNACOS_INIT_ADMIN_PASSWORD` after that point is therefore not documented as a supported way to reset an existing administrator.

For cluster deployments, `RNACOS_CLUSTER_TOKEN` is empty by default. Setting it restricts communication to nodes carrying the same token. The backup interface has a separate token setting, but the documentation says an empty value or one shorter than 32 characters leaves that interface disabled. These are concrete configuration boundaries, not claims that r-nacos supplies a complete security architecture.

Logging can affect volume as well as diagnostics. `RUST_LOG` accepts `debug`, `info`, `warn`, or `error`, and the README notes that all HTTP and gRPC requests are logged at `info`. Operators who need lower log volume can set it to `error`, but that reduces request-level visibility.

## Limits and the Difference from Java Nacos

The main alternative discussed in the README is Java Nacos. Both approaches serve the Nacos client-facing contract, configuration data, service instances, and administrative functions. The implementation approach differs: r-nacos is a Rust server distributed as the `rnacos` binary and Docker images. r-nacos also uses a local SQLite-backed data directory according to the dependency and configuration descriptions, while the README does not describe the official Java server's storage architecture.

r-nacos is the wrong choice when an application relies on a Nacos capability that is not among the documented HTTP OpenAPI, gRPC, console, or MCP functions. Protocol compatibility with current client SDKs does not prove parity for every server plugin, internal endpoint, operator workflow, or migration tool. The repository's inclusion of integration tests is useful, but the README excerpt does not enumerate complete compatibility coverage.

A second limitation is operational traceability. The README publishes configuration keys and installation methods, but it does not provide a formal upgrade procedure, rollback procedure, supported migration matrix, or compatibility policy for moving an existing Java Nacos database into r-nacos. Do not infer that changing a service address is sufficient for a production migration. Existing namespace data, groups, authentication state, cluster membership, and persistence format need an explicit rehearsal.

The MCP conversion feature also needs scope control. The README says ordinary HTTP interfaces registered to r-nacos can be exposed through r-nacos as MCP services, but it does not document authentication propagation, request filtering, tool schemas, or observability for those converted interfaces. Those are adoption boundaries, not documented guarantees.

## Release Cadence, Packaging, and Apache-2.0

The repository is not archived. Its last push was on 2026-08-30, and releases v0.8.7, v0.8.6, and v0.8.5 were published on 2026-08-30, 2026-07-27, and 2026-07-21 respectively. That record supports recent development activity, but it does not by itself establish production suitability or upgrade compatibility.

Docker packaging offers two documented variants. Versioned `qingpan/rnacos:$version` images use Debian slim and are described as larger with relatively higher runtime performance. The `$version-alpine` form uses Alpine and is described as smaller with relatively lower runtime performance. The `stable` and `stable-alpine` tags point to the latest formal release according to the README. Pinning a version is more predictable when reproducing a deployment, although the README does not prescribe a specific pinning policy.

The Cargo package identifies the server as Rust package `rnacos`, version `0.8.7`, with an optional `mimalloc` feature. Upgrades can therefore involve both the server image or binary and client compatibility assumptions. The repository includes `CHANGELOG.md`.

The project uses the `Apache-2.0` license. That matters for source redistribution and compliance obligations, including preservation of applicable notices and license text. This is not legal advice. Consumers should inspect the repository's `LICENSE` file and their own distribution requirements before packaging r-nacos.

## Conclusion

r-nacos is appropriate for developers replacing Nacos in local environments and for operators evaluating a lower-footprint Rust server, especially where Nacos client compatibility is required. It is a poor fit for an unsupported Nacos extension, a deployment that depends on undocumented parity, or any environment that has not validated persistence, authentication, and cluster behavior. Verify first that the intended client SDK can connect through both the HTTP and gRPC ports, then test configuration persistence and cluster settings before adoption.

## FAQ

### Does r-nacos work with standard Nacos client SDKs?

The README states that r-nacos supports the latest Nacos client-facing protocol, including Nacos 1.x HTTP OpenAPI and Nacos 2.x gRPC. It is intended to support migration of applications that already use Nacos services.

### How do I install and start r-nacos quickly?

With Cargo available, run `cargo install rnacos` and then `rnacos`. The README also documents binary archives, Docker, Docker Compose, Homebrew, apt, source builds, and Helm.

### Which ports does a default r-nacos Docker deployment expose?

The documented Docker command publishes `8848`, `9848`, and `10848`. They correspond to the HTTP service, the default gRPC port, and the separate management console port.

### Does r-nacos support clustered deployment and local data storage?

The README documents cluster settings based on Raft and identifies `RNACOS_DATA_DIR` as the local database directory. It does not provide detailed recovery or migration procedures.

### What license does r-nacos use?

Both the repository metadata and `Cargo.toml` identify the license as `Apache-2.0`.

## Sources

- [License: Apache-2.0](https://github.com/nacos-group/r-nacos/blob/master/LICENSE)
- [nacos-group/r-nacos on GitHub](https://github.com/nacos-group/r-nacos)
- [Project website](https://r-nacos.github.io/docs/)
- [README](https://github.com/nacos-group/r-nacos/blob/master/README.md)
- [Releases](https://github.com/nacos-group/r-nacos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nacos-group-r-nacos