From 502096a208f008680735238b357b04debf490231 Mon Sep 17 00:00:00 2001
From: jiesen <jiesen@jiesendeMacBook-Pro.local>
Date: Sun, 21 Dec 2025 01:24:02 +0700
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=20=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=E9=BB=98=E8=AE=A4=E7=AB=AF=E5=8F=A3=E4=B8=8E=E8=BF=90=E7=BB=B4?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     | 14 ++--
 docs/TECH_SPEC.md                             |  8 +-
 docs/content/01.introduction/3.quickstart.md  | 10 +--
 docs/content/02.user-guide/1.dashboard.md     |  2 +-
 docs/content/02.user-guide/11.skills.md       |  2 +-
 .../02.user-guide/4.configuration-example.md  |  6 +-
 .../02.user-guide/6.config-management.md      | 27 ++++++-
 docs/content/02.user-guide/8.api-server.md    | 10 +--
 docs/content/02.user-guide/9.mcp.md           |  2 +-
 docs/content/03.providers/7.codex.md          | 18 ++++-
 docs/content/04.api-reference/1.overview.md   |  6 +-
 docs/content/04.api-reference/2.openai-api.md |  6 +-
 docs/content/04.api-reference/3.claude-api.md |  6 +-
 .../04.api-reference/4.management-api.md      |  4 +
 .../05.troubleshooting/1.common-issues.md     |  4 +-
 .../05.troubleshooting/3.connection-issues.md |  2 +-
 docs/content/06.development/4.operations.md   | 55 ++++++++++++++
 docs/content/index.md                         |  4 +-
 docs/ops.md                                   | 74 +++++++++++++++++++
 19 files changed, 215 insertions(+), 45 deletions(-)
 create mode 100644 docs/content/06.development/4.operations.md
 create mode 100644 docs/ops.md

diff --git a/README.md b/README.md
index a022b3b31..099055482 100644
--- a/README.md
+++ b/README.md
@@ -75,7 +75,7 @@
 - **Per-Key 代理** - 为每个凭证单独配置代理
 
 ### 🔐 安全与管理
-- **TLS/HTTPS 支持** - 可选启用 HTTPS 加密通信
+- **HTTPS 部署** - 当前版本不内置 TLS，请使用反向代理进行 HTTPS 终止
 - **远程管理 API** - 通过 API 远程管理配置和凭证
 - **访问控制** - 支持 localhost 限制和密钥认证
 
@@ -145,8 +145,8 @@
 3. **启动服务** - 在 Dashboard 点击"启动服务器"
 4. **配置客户端** - 在 Cherry-Studio、Cline 等工具中配置：
    ```
-   API Base URL: http://localhost:3001/v1
-   API Key: proxycast-key
+   API Base URL: http://localhost:8999/v1
+   API Key: 启动时自动生成的密钥（可在设置页查看/修改）
    ```
 
 ---
@@ -156,9 +156,9 @@
 ### OpenAI Chat Completions
 
 ```bash
-curl http://localhost:3001/v1/chat/completions \
+curl http://localhost:8999/v1/chat/completions \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer proxycast-key" \
+  -H "Authorization: Bearer your-api-key" \
   -d '{
     "model": "claude-sonnet-4-5-20250514",
     "messages": [
@@ -171,9 +171,9 @@ curl http://localhost:3001/v1/chat/completions \
 ### Anthropic Messages API
 
 ```bash
-curl http://localhost:3001/v1/messages \
+curl http://localhost:8999/v1/messages \
   -H "Content-Type: application/json" \
-  -H "x-api-key: proxycast-key" \
+  -H "x-api-key: your-api-key" \
   -H "anthropic-version: 2023-06-01" \
   -d '{
     "model": "claude-sonnet-4-5-20250514",
diff --git a/docs/TECH_SPEC.md b/docs/TECH_SPEC.md
index 198fc0590..a9fa1c35f 100644
--- a/docs/TECH_SPEC.md
+++ b/docs/TECH_SPEC.md
@@ -85,8 +85,8 @@ src/
 ### 路由模式
 
 ```
-http://localhost:3000/{provider}/v1/chat/completions
-http://localhost:3000/{provider}/v1/messages
+http://localhost:8999/{provider}/v1/chat/completions
+http://localhost:8999/{provider}/v1/messages
 ```
 
 ### 支持的端点
@@ -104,8 +104,8 @@ http://localhost:3000/{provider}/v1/messages
 {
   "server": {
     "host": "127.0.0.1",
-    "port": 3000,
-    "apiKey": "proxycast-key"
+    "port": 8999,
+    "apiKey": "your-api-key"
   },
   "providers": {
     "kiro": {
diff --git a/docs/content/01.introduction/3.quickstart.md b/docs/content/01.introduction/3.quickstart.md
index ea6cce540..55f1aee9d 100644
--- a/docs/content/01.introduction/3.quickstart.md
+++ b/docs/content/01.introduction/3.quickstart.md
@@ -46,7 +46,7 @@ ProxyCast 会自动检测本地的 AI 客户端凭证文件。
 
 1. 在仪表盘点击 **启动服务**
 2. 服务状态变为"运行中"
-3. 记下 API 地址（默认 `http://127.0.0.1:9090`）
+3. 记下 API 地址（默认 `http://127.0.0.1:8999`）
 
 ## 步骤 4: 测试 API
 
@@ -61,7 +61,7 @@ ProxyCast 会自动检测本地的 AI 客户端凭证文件。
 **OpenAI 格式:**
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key" \
   -d '{
@@ -73,7 +73,7 @@ curl http://127.0.0.1:9090/v1/chat/completions \
 **Claude 格式:**
 
 ```bash
-curl http://127.0.0.1:9090/v1/messages \
+curl http://127.0.0.1:8999/v1/messages \
   -H "Content-Type: application/json" \
   -H "x-api-key: your-api-key" \
   -H "anthropic-version: 2023-06-01" \
@@ -90,7 +90,7 @@ curl http://127.0.0.1:9090/v1/messages \
 
 在 Cursor 设置中配置 OpenAI API：
 
-- API Base URL: `http://127.0.0.1:9090/v1`
+- API Base URL: `http://127.0.0.1:8999/v1`
 - API Key: 你在 ProxyCast 中设置的 API Key
 
 ### Continue 配置
@@ -103,7 +103,7 @@ curl http://127.0.0.1:9090/v1/messages \
     "title": "ProxyCast Claude",
     "provider": "openai",
     "model": "claude-sonnet-4-20250514",
-    "apiBase": "http://127.0.0.1:9090/v1",
+    "apiBase": "http://127.0.0.1:8999/v1",
     "apiKey": "your-api-key"
   }]
 }
diff --git a/docs/content/02.user-guide/1.dashboard.md b/docs/content/02.user-guide/1.dashboard.md
index cc7f04281..c0d820de7 100644
--- a/docs/content/02.user-guide/1.dashboard.md
+++ b/docs/content/02.user-guide/1.dashboard.md
@@ -29,7 +29,7 @@ navigation:
 
 服务运行时显示：
 
-- **API 地址**: 本地 API 端点（如 `http://127.0.0.1:9090`）
+- **API 地址**: 本地 API 端点（如 `http://127.0.0.1:8999`）
 - **API Key**: 当前配置的访问密钥
 - **复制按钮**: 一键复制 API 地址或 Key
 
diff --git a/docs/content/02.user-guide/11.skills.md b/docs/content/02.user-guide/11.skills.md
index 44dfe4378..1ef9c6403 100644
--- a/docs/content/02.user-guide/11.skills.md
+++ b/docs/content/02.user-guide/11.skills.md
@@ -101,7 +101,7 @@ coding:
 ### 通过 API 调用
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key" \
   -d '{
diff --git a/docs/content/02.user-guide/4.configuration-example.md b/docs/content/02.user-guide/4.configuration-example.md
index b25224a62..eae3c1cc7 100644
--- a/docs/content/02.user-guide/4.configuration-example.md
+++ b/docs/content/02.user-guide/4.configuration-example.md
@@ -16,7 +16,7 @@ navigation:
 server:
   host: "127.0.0.1"
   port: 8999
-  api_key: "proxy_cast"
+  api_key: "your-api-key"
   
   # TLS/HTTPS 配置
   tls:
@@ -24,6 +24,8 @@ server:
     cert_path: "/path/to/cert.pem"
     key_path: "/path/to/key.pem"
 
+# 注意：当前版本暂不支持 TLS。启用后服务将无法启动，请使用反向代理做 TLS 终止。
+
 # 全局代理 URL（支持 socks5/http/https）
 proxy_url: "socks5://127.0.0.1:1080"
 
@@ -278,7 +280,7 @@ injection:
 server:
   host: "127.0.0.1"
   port: 8999
-  api_key: "proxy_cast"
+  api_key: "your-api-key"
   tls:
     enable: false
     cert_path: ""
diff --git a/docs/content/02.user-guide/6.config-management.md b/docs/content/02.user-guide/6.config-management.md
index 6b0023bd3..ad245078e 100644
--- a/docs/content/02.user-guide/6.config-management.md
+++ b/docs/content/02.user-guide/6.config-management.md
@@ -56,7 +56,7 @@ resilience:
 
 server:
   host: "127.0.0.1"
-  port: 9090
+  port: 8999
 ```
 
 ### 敏感信息处理
@@ -107,15 +107,15 @@ server:
 
 ```bash
 # ProxyCast API Configuration
-PROXYCAST_API_BASE=http://127.0.0.1:9090/v1
+PROXYCAST_API_BASE=http://127.0.0.1:8999/v1
 PROXYCAST_API_KEY=your-api-key
 
 # OpenAI Compatible
-OPENAI_API_BASE=http://127.0.0.1:9090/v1
+OPENAI_API_BASE=http://127.0.0.1:8999/v1
 OPENAI_API_KEY=your-api-key
 
 # Claude Compatible
-ANTHROPIC_API_BASE=http://127.0.0.1:9090
+ANTHROPIC_API_BASE=http://127.0.0.1:8999
 ANTHROPIC_API_KEY=your-api-key
 ```
 
@@ -142,6 +142,25 @@ ProxyCast 会自动备份配置：
 3. 选择要恢复的版本
 4. 点击 **恢复**
 
+## 完整备份与恢复（生产建议）
+
+仅导出配置无法覆盖数据库与凭证文件。生产环境建议定期备份以下路径：
+
+- 配置文件：macOS `~/Library/Application Support/proxycast/config.yaml`；Linux `~/.config/proxycast/config.yaml`；Windows `%APPDATA%\\proxycast\\config.yaml`
+- 凭证副本目录：macOS `~/Library/Application Support/proxycast/credentials/`；Linux `~/.local/share/proxycast/credentials/`；Windows `%APPDATA%\\proxycast\\credentials\\`
+- 数据库与日志：`~/.proxycast/`（含 `proxycast.db`、`logs/`、`request_logs/`、`auth/`）
+
+```bash
+# 示例：备份数据库与日志目录
+cp -a ~/.proxycast ~/.proxycast.backup-$(date +%Y%m%d%H%M%S)
+```
+
+恢复时将备份内容替换回原路径，并确保应用已退出。
+
+## 旧版本迁移说明
+
+如果检测到旧版 `~/.proxycast/config.json`，当前版本会阻止启动并提示手动迁移。请先导出旧配置或重新导入 YAML 配置，再启动应用。
+
 ## 配置同步
 
 ### 跨设备同步
diff --git a/docs/content/02.user-guide/8.api-server.md b/docs/content/02.user-guide/8.api-server.md
index ca041f8d0..fc94ea0dd 100644
--- a/docs/content/02.user-guide/8.api-server.md
+++ b/docs/content/02.user-guide/8.api-server.md
@@ -16,7 +16,7 @@ API Server 是 ProxyCast 的核心组件，提供 OpenAI/Claude 兼容的 API 
 | 选项 | 默认值 | 说明 |
 |------|--------|------|
 | 主机地址 | `127.0.0.1` | 监听地址 |
-| 端口 | `9090` | 监听端口 |
+| 端口 | `8999` | 监听端口 |
 | API Key | 自动生成 | 访问密钥 |
 
 ### 配置步骤
@@ -31,10 +31,10 @@ API Server 是 ProxyCast 的核心组件，提供 OpenAI/Claude 兼容的 API 
 | 地址 | 说明 |
 |------|------|
 | `127.0.0.1` | 仅本机访问 |
-| `0.0.0.0` | 允许局域网访问 |
+| `localhost` | 仅本机访问 |
 
 ::alert{type="warning"}
-使用 `0.0.0.0` 时请确保配置了 API Key 认证。
+当前版本仅支持本地监听（127.0.0.1/localhost/::1），不支持对外开放。
 ::
 
 ## API 端点
@@ -99,7 +99,7 @@ API Server 是 ProxyCast 的核心组件，提供 OpenAI/Claude 兼容的 API 
 
 **OpenAI 格式:**
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Authorization: Bearer your-api-key" \
   -H "Content-Type: application/json" \
   -d '{"model": "gpt-4", "messages": [...]}'
@@ -107,7 +107,7 @@ curl http://127.0.0.1:9090/v1/chat/completions \
 
 **Claude 格式:**
 ```bash
-curl http://127.0.0.1:9090/v1/messages \
+curl http://127.0.0.1:8999/v1/messages \
   -H "x-api-key: your-api-key" \
   -H "anthropic-version: 2023-06-01" \
   -H "Content-Type: application/json" \
diff --git a/docs/content/02.user-guide/9.mcp.md b/docs/content/02.user-guide/9.mcp.md
index cf3c251aa..d6f234639 100644
--- a/docs/content/02.user-guide/9.mcp.md
+++ b/docs/content/02.user-guide/9.mcp.md
@@ -93,7 +93,7 @@ MCP 定义了 AI 模型与外部系统交互的标准方式：
 通过 API 调用 MCP 工具：
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key" \
   -d '{
diff --git a/docs/content/03.providers/7.codex.md b/docs/content/03.providers/7.codex.md
index 4083b385f..7b6358c5d 100644
--- a/docs/content/03.providers/7.codex.md
+++ b/docs/content/03.providers/7.codex.md
@@ -11,7 +11,8 @@ navigation:
 
 ## 概述
 
-Codex Provider 允许你使用 OpenAI Codex 的 OAuth 凭证访问 GPT 模型，无需 API Key。
+Codex Provider 允许你使用 OpenAI Codex 的 OAuth 凭证访问 GPT 模型。
+同时，为了兼容 Codex CLI 的「API Key 登录」用户（`~/.codex/auth.json` 只有 `api_key`），ProxyCast 也支持读取 `api_key` 并作为 Bearer Token 使用（无需刷新）。
 
 ## 支持的模型
 
@@ -54,6 +55,8 @@ credential_pool:
 
 ### Token 文件格式
 
+#### OAuth 模式（推荐用于 Codex OAuth）
+
 ```json
 {
   "access_token": "eyJ...",
@@ -63,6 +66,19 @@ credential_pool:
 }
 ```
 
+#### API Key 模式（兼容 Codex CLI）
+
+```json
+{
+  "api_key": "sk-xxx",
+  "api_base_url": "https://api.openai.com" 
+}
+```
+
+说明：
+- `api_key` / `apiKey`：必填
+- `api_base_url` / `apiBaseUrl`：可选；可填写 `https://api.openai.com` 或带 `/v1` 的地址（例如网关、反代、Azure 兼容地址）
+
 ## Token 刷新
 
 ProxyCast 会自动在 Token 过期前刷新：
diff --git a/docs/content/04.api-reference/1.overview.md b/docs/content/04.api-reference/1.overview.md
index 1067a7965..2b3919ec1 100644
--- a/docs/content/04.api-reference/1.overview.md
+++ b/docs/content/04.api-reference/1.overview.md
@@ -50,7 +50,7 @@ ProxyCast 提供 OpenAI 和 Claude 兼容的 API 端点。
 使用 `Authorization` 头：
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Authorization: Bearer your-api-key" \
   -H "Content-Type: application/json" \
   -d '...'
@@ -61,7 +61,7 @@ curl http://127.0.0.1:9090/v1/chat/completions \
 使用 `x-api-key` 头：
 
 ```bash
-curl http://127.0.0.1:9090/v1/messages \
+curl http://127.0.0.1:8999/v1/messages \
   -H "x-api-key: your-api-key" \
   -H "anthropic-version: 2023-06-01" \
   -H "Content-Type: application/json" \
@@ -70,7 +70,7 @@ curl http://127.0.0.1:9090/v1/messages \
 
 ## 基础 URL
 
-默认地址：`http://127.0.0.1:9090`
+默认地址：`http://127.0.0.1:8999`
 
 可在设置中修改主机和端口。
 
diff --git a/docs/content/04.api-reference/2.openai-api.md b/docs/content/04.api-reference/2.openai-api.md
index 30d35ba91..eecdd54d3 100644
--- a/docs/content/04.api-reference/2.openai-api.md
+++ b/docs/content/04.api-reference/2.openai-api.md
@@ -92,7 +92,7 @@ Authorization: Bearer your-api-key
 设置 `stream: true` 启用流式响应：
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Authorization: Bearer your-api-key" \
   -H "Content-Type: application/json" \
   -d '{
@@ -202,7 +202,7 @@ Authorization: Bearer your-api-key
 import openai
 
 client = openai.OpenAI(
-    base_url="http://127.0.0.1:9090/v1",
+    base_url="http://127.0.0.1:8999/v1",
     api_key="your-api-key"
 )
 
@@ -220,7 +220,7 @@ print(response.choices[0].message.content)
 import OpenAI from 'openai';
 
 const client = new OpenAI({
-  baseURL: 'http://127.0.0.1:9090/v1',
+  baseURL: 'http://127.0.0.1:8999/v1',
   apiKey: 'your-api-key'
 });
 
diff --git a/docs/content/04.api-reference/3.claude-api.md b/docs/content/04.api-reference/3.claude-api.md
index cbafe61fb..e5055e037 100644
--- a/docs/content/04.api-reference/3.claude-api.md
+++ b/docs/content/04.api-reference/3.claude-api.md
@@ -93,7 +93,7 @@ anthropic-version: 2023-06-01
 设置 `stream: true` 启用流式响应：
 
 ```bash
-curl http://127.0.0.1:9090/v1/messages \
+curl http://127.0.0.1:8999/v1/messages \
   -H "x-api-key: your-api-key" \
   -H "anthropic-version: 2023-06-01" \
   -H "Content-Type: application/json" \
@@ -200,7 +200,7 @@ anthropic-version: 2023-06-01
 import anthropic
 
 client = anthropic.Anthropic(
-    base_url="http://127.0.0.1:9090",
+    base_url="http://127.0.0.1:8999",
     api_key="your-api-key"
 )
 
@@ -219,7 +219,7 @@ print(message.content[0].text)
 import Anthropic from '@anthropic-ai/sdk';
 
 const client = new Anthropic({
-  baseURL: 'http://127.0.0.1:9090',
+  baseURL: 'http://127.0.0.1:8999',
   apiKey: 'your-api-key'
 });
 
diff --git a/docs/content/04.api-reference/4.management-api.md b/docs/content/04.api-reference/4.management-api.md
index 84515cdd9..481130e55 100644
--- a/docs/content/04.api-reference/4.management-api.md
+++ b/docs/content/04.api-reference/4.management-api.md
@@ -26,6 +26,10 @@ Authorization: Bearer your-secret-key
 | `secret_key` | 管理密钥，为空时禁用所有管理端点（返回 404） |
 | `allow_remote` | 是否允许远程访问，为 false 时仅允许 localhost |
 
+::alert{type="warning"}
+当前版本未启用 TLS，仅支持本地访问，`allow_remote` 必须保持为 `false`。
+::
+
 ## /v0/management/status
 
 获取服务器状态信息。
diff --git a/docs/content/05.troubleshooting/1.common-issues.md b/docs/content/05.troubleshooting/1.common-issues.md
index c8d3e4b4a..ddf5e6de4 100644
--- a/docs/content/05.troubleshooting/1.common-issues.md
+++ b/docs/content/05.troubleshooting/1.common-issues.md
@@ -30,10 +30,10 @@ navigation:
 ```bash
 # 查找占用端口的进程
 # macOS/Linux
-lsof -i :9090
+lsof -i :8999
 
 # Windows
-netstat -ano | findstr :9090
+netstat -ano | findstr :8999
 ```
 
 或在设置中更改端口号。
diff --git a/docs/content/05.troubleshooting/3.connection-issues.md b/docs/content/05.troubleshooting/3.connection-issues.md
index a702342f5..b23dd7bd4 100644
--- a/docs/content/05.troubleshooting/3.connection-issues.md
+++ b/docs/content/05.troubleshooting/3.connection-issues.md
@@ -152,7 +152,7 @@ export NO_PROXY=localhost,127.0.0.1
 | 端口 | 用途 |
 |------|------|
 | 443 | HTTPS 请求 |
-| 9090 | ProxyCast API（默认） |
+| 8999 | ProxyCast API（默认） |
 
 ### macOS 防火墙
 
diff --git a/docs/content/06.development/4.operations.md b/docs/content/06.development/4.operations.md
new file mode 100644
index 000000000..6403cf3cb
--- /dev/null
+++ b/docs/content/06.development/4.operations.md
@@ -0,0 +1,55 @@
+---
+title: 上线运维
+description: 生产就绪的最小运维清单
+navigation:
+  icon: i-heroicons-wrench-screwdriver
+---
+
+# 上线运行与运维（生产就绪最小版）
+
+本页面用于“马上上线且长期稳定运行”的最小运维闭环，避免上线后因配置、备份或回滚缺失导致不可恢复的问题。
+
+## 上线前检查
+
+- 确认服务仅本地监听：`server.host = 127.0.0.1`（当前版本仅支持本地监听）
+- 设置强 API Key：不要使用默认值 `proxy_cast`
+- 确认日志保留策略：`logging.retention_days` 合理（建议 >= 7 天）
+- 确认凭证与配置已正确导入，并完成一次启动 + 健康检查
+
+## 运行健康检查
+
+- HTTP 健康检查：`GET /health`
+- 关键字段应包含 `status=healthy` 与 `version`
+- 建议在上线后做一次 API 冒烟请求（如 `/v1/models`）
+
+## 备份与恢复（必须）
+
+当前版本需要手动备份以下路径：
+
+- 配置文件（macOS: `~/Library/Application Support/proxycast/config.yaml`，Linux: `~/.config/proxycast/config.yaml`，Windows: `%APPDATA%\\proxycast\\config.yaml`）
+- 凭证池副本目录（导入的凭证文件）：macOS `~/Library/Application Support/proxycast/credentials/`，Linux `~/.local/share/proxycast/credentials/`，Windows `%APPDATA%\\proxycast\\credentials\\`
+- OAuth 凭证目录：`~/.proxycast/auth/`
+- 数据库文件：`~/.proxycast/proxycast.db`
+- 日志目录：`~/.proxycast/logs/`、`~/.proxycast/request_logs/`
+
+恢复步骤（顺序建议）：
+
+1. 停止应用
+2. 恢复 `config.yaml`
+3. 恢复 `credentials` 目录、`auth` 目录与数据库 `proxycast.db`
+4. 如需保留历史日志，恢复 `logs/` 与 `request_logs/`
+5. 启动应用并验证 `/health` 与关键功能
+
+## 回滚策略
+
+- 如果升级失败，恢复备份的 `config.yaml` 与 `proxycast.db`
+- 使用上一版本安装包覆盖安装
+- 完成健康检查与冒烟测试
+
+## 发布质量门槛（最小）
+
+- `cd src-tauri && cargo test`
+- `cd src-tauri && cargo clippy`
+- `npm test`
+- `npm run lint`
+- `npm run build`
diff --git a/docs/content/index.md b/docs/content/index.md
index 98798d15a..b7a0701c2 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -81,12 +81,12 @@ ProxyCast 会自动检测本地的 AI 客户端凭证文件：
 
 ### 3. 启动服务
 
-点击仪表盘的「启动服务」按钮，API Server 默认运行在 `http://127.0.0.1:9090`。
+点击仪表盘的「启动服务」按钮，API Server 默认运行在 `http://127.0.0.1:8999`。
 
 ### 4. 测试 API
 
 ```bash
-curl http://127.0.0.1:9090/v1/chat/completions \
+curl http://127.0.0.1:8999/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer your-api-key" \
   -d '{
diff --git a/docs/ops.md b/docs/ops.md
new file mode 100644
index 000000000..fffd3c71e
--- /dev/null
+++ b/docs/ops.md
@@ -0,0 +1,74 @@
+# 生产运维与上线就绪清单
+
+本文档用于生产环境部署、运行、备份与恢复的最小操作规范，避免上线后缺少可执行流程。
+
+## 部署前检查
+
+- 确认 API Key 已更换（禁止使用默认值 `proxy_cast`）。
+- 确认监听地址：
+  - 本机使用 `127.0.0.1`/`localhost`。
+- 当前版本仅支持本地监听，不支持对外服务。
+- 若需要 HTTPS，请使用反向代理终止 TLS；当前服务端未启用内置 TLS。
+- 确认磁盘权限可写：`~/.proxycast/`、`~/.proxycast/request_logs/`、应用数据目录（macOS: `~/Library/Application Support/proxycast/`，Linux: `~/.local/share/proxycast/`，Windows: `%APPDATA%\\proxycast\\`）。
+
+## 配置路径与加载顺序
+
+- YAML 配置（优先）：
+  - macOS: `~/Library/Application Support/proxycast/config.yaml`
+  - Linux: `~/.config/proxycast/config.yaml`
+  - Windows: `%APPDATA%\\proxycast\\config.yaml`
+- JSON 配置（兼容）：macOS `~/Library/Application Support/proxycast/config.json`，Linux `~/.config/proxycast/config.json`，Windows `%APPDATA%\\proxycast\\config.json`
+- 旧版遗留路径：`~/.proxycast/config.json`（检测到会提示手动迁移）
+- 两者都不存在时使用默认配置。
+
+## 数据与日志位置
+
+- SQLite 数据库：`~/.proxycast/proxycast.db`
+- 凭证池副本目录：macOS `~/Library/Application Support/proxycast/credentials/`，Linux `~/.local/share/proxycast/credentials/`，Windows `%APPDATA%\\proxycast\\credentials\\`
+- OAuth/Token 目录（默认）：`~/.proxycast/auth/`
+- 日志目录：`~/.proxycast/logs/`
+- 请求日志目录：`~/.proxycast/request_logs/`
+
+## 备份与恢复
+
+### 备份
+
+1. 停止 ProxyCast 服务。
+2. 复制以下路径：
+   - 配置文件（macOS: `~/Library/Application Support/proxycast/config.yaml`，Linux: `~/.config/proxycast/config.yaml`，Windows: `%APPDATA%\\proxycast\\config.yaml`）
+   - 凭证池副本目录（macOS: `~/Library/Application Support/proxycast/credentials/`，Linux: `~/.local/share/proxycast/credentials/`，Windows: `%APPDATA%\\proxycast\\credentials\\`）
+   - `~/.proxycast/proxycast.db`
+   - `~/.proxycast/auth/`（如需要保留 OAuth/Token）
+   - `~/.proxycast/logs/`、`~/.proxycast/request_logs/`（如需保留日志）
+3. 将备份文件存入受控存储（加密磁盘或安全存储）。
+
+### 恢复
+
+1. 停止 ProxyCast 服务。
+2. 恢复上述文件到原路径。
+3. 启动服务并检查 `/health`。
+
+## 升级与回滚
+
+- 升级前执行备份流程。
+- 升级后若出现异常：
+  - 恢复备份文件。
+  - 回滚到上一个稳定版本的安装包。
+
+## 运行与排障
+
+- 健康检查：`GET /health`
+- 常见问题排查：
+  - 端口占用：修改配置端口或释放占用端口。
+  - 配置解析失败：检查 YAML/JSON 语法，确认缩进正确。
+  - 数据库初始化失败：检查 `~/.proxycast/` 权限与磁盘空间。
+
+## 安全基线
+
+- 禁止默认 API key。
+- 当前版本未实现内置 TLS，远程管理必须保持关闭且仅本地访问。
+
+## 管理 API 基线
+
+- 管理 API 启用后会对失败认证进行短期限制，避免暴力尝试。
+- 建议仅在内网使用，并配合独立强密钥。