From df81b0d209f7bc216d4069a0eee71e3a718d54db Mon Sep 17 00:00:00 2001
From: Bifang <915779419@qq.com>
Date: Tue, 29 Sep 2026 09:52:03 +0800
Subject: [PATCH] docs: add non-Docker server startup guide

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 20dbc01..0dbb4d7 100644
--- a/README.md
+++ b/README.md
@@ -241,6 +241,50 @@ docker compose up -d
 
 > Detailed deployment instructions: [Deployment Guide](./docs/deployment.md)
 
+### 2. Non-Docker Deployment (Linux Server)
+
+Run the FastAPI service directly on the server when you want to test without Docker. The commands below use NVIDIA as an example; use the matching `scripts/sync_*_env.sh` script for CPU or a vendor GPU backend (see the table in [Local Development](#local-development)).
+
+**Requirements:** Python 3.10–3.12, `uv`, FFmpeg, and the server's supported accelerator driver/runtime. The default NVIDIA environment installs the CUDA 13.0 PyTorch/vLLM stack from the project lock file.
+
+```bash
+# From the project root
+python3 --version
+uv --version
+
+# Install the NVIDIA environment. For CPU, use ./scripts/sync_cpu_env.sh.
+./scripts/sync_gpu_env.sh
+
+# Copy the sample settings, then edit .env if needed.
+cp .env.example .env
+```
+
+Set `HOST=0.0.0.0` and `PORT=8000` in `.env` if you want to access the service from another machine. Set `API_KEY` to enable authentication; it is optional for a local test. Model files use `./models` by default. To store them elsewhere, set `MODELS_DIR`, `MODELSCOPE_CACHE`, and `MODELSCOPE_PATH` in `.env` as described in the sample file.
+
+Download the models before starting so the first server launch does not wait for model downloads:
+
+```bash
+./scripts/download-models.sh --models-dir ./models --python-bin ./.venv/bin/python --mode local
+```
+
+This step requires access to ModelScope. If you skip it, `start.py` checks for missing models and attempts to download them during startup.
+
+Start the service in the foreground and watch the startup logs:
+
+```bash
+./.venv/bin/python start.py
+```
+
+The default endpoint is `http://<server-ip>:8000`; open port `8000` in the server firewall if you are connecting remotely. Check the service and open the interactive API docs at `http://<server-ip>:8000/docs`. To test transcription with an audio file:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/audio/transcriptions \
+  -H "Authorization: Bearer your_api_key" \
+  -F "file=@/path/to/test.wav"
+```
+
+Replace `your_api_key` with the value in `.env`. If `API_KEY` is unset, omit the `Authorization` header. Stop the foreground process with `Ctrl+C`.
+
 ### Local Development
 
 **System Requirements:**