# nacos-console

**Repository Path**: chenxxxxxxxx/nacos-console

## Basic Information

- **Project Name**: nacos-console
- **Description**: Nacos 控制台
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nacos Console

> A single-binary BFF (Backend for Frontend) console that replaces the official Nacos console, built on the Nacos v1-compatible HTTP OpenAPI; compatible with the whole Nacos 2.x line and most 1.4.x.

## Overview

The **primary goal** of this console is to eliminate the **cleartext password transmission** on the official Nacos login endpoint `/nacos/v1/auth/users/login`, which triggers WAF (e.g. Sangfor) interception and alerts.

No Nacos cleartext password ever travels between the browser and the console: the real Nacos credentials are held server-side and stored encrypted. The frontend talks only to this console's BFF, which logs in to Nacos on the server side and reverse-proxies all OpenAPI calls.

## Features

- **Zero-cleartext login**: the browser sends only the **sha256 digest** of the account password; the backend stores and verifies it as `bcrypt(sha256hex)`.
- **Encrypted Nacos credentials**: the real Nacos password is held by the backend and stored with **AES-256-GCM**; the master key is injected via the `CONSOLE_MASTER_KEY` environment variable (base64-encoded 32 bytes).
- **Server-side proxy**: the backend logs in to Nacos using stored credentials, caches and auto-refreshes the `accessToken`, then reverse-proxies all Nacos v1 OpenAPI calls.
- **Single-binary delivery**: the frontend build is embedded via Go `embed` into one executable; uses pure-Go SQLite (`modernc.org/sqlite`), **CGO-free**, cross-compilable to any platform.
- **Full functionality**: config management, services/instances, namespaces, clusters, users, operation audit, and Nacos connection settings.
- **Sub-path deployment**: can be mounted under an nginx sub-path (e.g. `/admin`) via `BASE_PATH`.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Frontend | React 18 + TypeScript + Vite 5 + Arco Design |
| Routing/State | react-router-dom v6 + zustand |
| Frontend HTTP | axios (injects JWT on request; auto-redirects to login on 401) |
| Backend | Go 1.26 + Gin |
| Storage | SQLite (`modernc.org/sqlite`, pure Go, CGO-free) |
| Crypto | AES-256-GCM (at-rest) + bcrypt (passwords) + JWT (sessions) |
| Packaging | Frontend embedded via Go `embed`, single binary output |

## Architecture

```mermaid
graph LR
    Browser[Browser SPA<br/>React + Arco]
    subgraph Console[Nacos Console single binary]
        Static[Embedded frontend<br/>go:embed]
        Auth[Auth<br/>sha256+bcrypt+JWT]
        Settings[Settings<br/>AES-256-GCM]
        Token[Token manager<br/>accessToken cache/refresh]
        Proxy[Reverse proxy<br/>Nacos v1 OpenAPI]
        DB[(SQLite)]
    end
    Nacos[Nacos 2.x]

    Browser -->|sha256 pwd / JWT| Auth
    Browser --> Static
    Auth --> DB
    Settings --> DB
    Auth --> Proxy
    Proxy --> Token
    Token -->|server-side login| Nacos
    Proxy -->|forward OpenAPI| Nacos
```

Request flow: the browser talks only to the console BFF (sending just the sha256 password and a JWT); the backend retrieves the encrypted Nacos credentials, performs a server-side login, caches the `accessToken`, and reverse-proxies all Nacos OpenAPI calls. The Nacos cleartext password never appears on the browser side.

## Directory Structure

```
nacos-console/
├── backend/                 # Go backend
│   ├── main.go              # entrypoint (with -version flag)
│   └── internal/
│       ├── config/          # env loading & validation
│       ├── crypto/          # AES-256-GCM encrypt/decrypt
│       ├── store/           # SQLite storage layer + migrations
│       ├── auth/            # login (sha256+bcrypt+JWT), password change
│       ├── nacos/           # credentials, accessToken manager, reverse proxy
│       ├── settings/        # Nacos connection settings (encrypted I/O, connectivity test)
│       └── server/          # routing, audit middleware, static embedding
├── frontend/                # React frontend (Vite + Arco Design)
│   └── src/
│       ├── api/             # client.ts (axios+login) / nacos.ts (API wrappers)
│       ├── store/           # zustand session state
│       ├── layout/          # main layout (side menu + top bar)
│       └── pages/           # Login/Configs/Services/Namespaces/Cluster/Users/Audit/Settings
├── deploy/                  # production deployment (systemd + Docker + Nginx)
└── docs/                    # project documentation
```

## Quick Start

```bash
# 1. Build the frontend
cd frontend && pnpm install && pnpm build

# 2. Compile the backend (with embedded frontend)
cd ../backend && go build -o console.exe .

# 3. Set the master key and run
export CONSOLE_MASTER_KEY=$(openssl rand -base64 32)   # required: AES master key
export CONSOLE_ADMIN_PASSWORD=admin123                 # example only, replace with a strong password
./console.exe
```

Open `http://127.0.0.1:8080` in your browser, log in with `admin` / your password. After the forced password change on first login, go to "Nacos Connection Settings" to configure the Nacos address and credentials.

### Requirements

| Tool | Version | Purpose |
|------|---------|---------|
| Go | 1.26+ | Backend compilation |
| Node.js | 20+ | Frontend build |
| pnpm | 8+ | Frontend package manager |

## Deployment

For production deployment (bare-metal/VM + systemd, Docker Compose, Nginx sub-path reverse proxy, etc.), see [deploy/README.md](./deploy/README.md).

## Documentation

| Document | Content |
|----------|---------|
| [docs/编译与使用指南.md](./docs/编译与使用指南.md) | Main doc: overview, tech stack, environment setup, build, run, env vars, feature guide, API list, troubleshooting |
| [deploy/README.md](./deploy/README.md) | Production deployment guide (systemd / Docker / Nginx; install, upgrade, backup, uninstall) |

## License

See [LICENSE](./LICENSE).