feat(docs): add screenshots + beginner install guide, MIBP Edition credits

2026-08-07 12:48:39 +08:00
parent 7929464427
commit d00205511a
9 changed files with 172 additions and 1332 deletions
@@ -2,22 +2,159 @@

 9Router is a local AI routing gateway with provider fallback and token-saving features.

-## Quick Start
+![9Router](images/9router.png)

-### Install
+## New Features

-#### Docker
+### Proxy Fitness
+
+Monitor proxy health and egress location to keep routed requests reliable.
+
+![Proxy Fitness](images/proxy-fitnes.png)
+
+### Smart Rotation
+
+Automatically rotate proxy pools and provider connections for better availability.
+
+![Smart Rotation](images/smart-rotation.png)
+
+## Installation for Beginners
+
+The easiest installation method is Docker. Docker runs 9Router in a container, so you do not need to install Node.js, npm, or the application dependencies manually.
+
+### 1. Install Docker
+
+Install Docker Desktop on Windows or macOS, or install Docker Engine and Docker Compose on Linux:
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [Docker Engine for Linux](https://docs.docker.com/engine/install/)
+
+After installation, open a terminal and check that Docker is available:
+
+```bash
+docker --version
+docker compose version
+```
+
+Both commands should print a version number.
+
+### 2. Download the project
+
+Clone this repository, then enter its folder:
+
+```bash
+git clone https://github.com/mhiqrambg/9router-mibp-version.git
+cd 9router-mibp-version
+```
+
+If Git is not installed, download the repository as a ZIP file from GitHub and open the extracted folder in a terminal.
+
+### 3. Create the environment file
+
+Create `.env` from the example file:

 ```bash
 cp .env.example .env
+```
+
+Open `.env` in a text editor and change at least these values:
+
+```env
+JWT_SECRET=replace-with-a-long-random-secret
+INITIAL_PASSWORD=replace-with-your-dashboard-password
+API_KEY_SECRET=replace-with-another-long-random-secret
+MACHINE_ID_SALT=replace-with-another-random-secret
+REQUIRE_API_KEY=true
+```
+
+Do not share `.env` or commit it to Git. It contains the dashboard password and security secrets. On Linux or macOS, you can generate random values with:
+
+```bash
+openssl rand -hex 32
+```
+
+Use a different generated value for each secret.
+
+### 4. Start 9Router
+
+Run this command in the project folder:
+
+```bash
 docker compose up -d
 ```

-Dashboard: `http://localhost:20128/dashboard`
+The first run downloads the 9Router and Headroom images. The `-d` option keeps them running in the background.

-API endpoint: `http://localhost:20128/v1`
+Check the containers:

-#### From Source
+```bash
+docker compose ps
+```
+
+Both `9router` and `headroom` should have a running status.
+
+### 5. Open the dashboard
+
+Open this address in your browser:
+
+```text
+http://localhost:20128/dashboard
+```
+
+Log in with the `INITIAL_PASSWORD` value from `.env`.
+
+### 6. Create an API key
+
+In the dashboard, open **Endpoint & Key** and create a key. Keep the complete key that starts with `sk-`.
+
+Use it when calling the API:
+
+```bash
+curl http://localhost:20128/v1/models \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+For a server exposed through a domain, replace the URL with your domain:
+
+```bash
+curl https://your-domain.example/v1/models \
+  -H "Authorization: Bearer YOUR_API_KEY"
+```
+
+Remote requests without a valid API key are rejected. The API key is stored in the application database, not in `.env`.
+
+### Useful Docker commands
+
+View live logs:
+
+```bash
+docker compose logs -f 9router
+```
+
+Restart the application:
+
+```bash
+docker compose restart 9router
+```
+
+Stop the services without deleting data:
+
+```bash
+docker compose down
+```
+
+Update to the latest image:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+The Docker volume named `9router-data` keeps your settings, providers, and API keys when the container is recreated.
+
+### Install from source
+
+This option is intended for development. Install Node.js 22 or newer, then run:

 ```bash
 cp .env.example .env
@@ -25,7 +162,7 @@ npm install
 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
 ```

-Before starting, set at least `JWT_SECRET` and `INITIAL_PASSWORD` in `.env`.
+Open `http://localhost:20128/dashboard` after the development server starts.

 ### Update