chore: rebuild dev/1.0.0 from main with docs and deploy config

- Rebase dev/1.0.0 on latest upstream main (drop Muse relay code) - Preserve: troubleshooting records, remote layout, Docker deploy workflow - Simplify docker-compose.yml to app-only (external PG/Redis) - Add ops/remote/ host documentation - Update .env.example with host/docker connection profiles
2026-05-18 23:39:31 +08:00 · 2026-05-18 23:39:31 +08:00 · e6bced5dc2
commit e6bced5dc2
parent 5dd0d3bcbd
10 changed files with 675 additions and 134 deletions
--- a/.env.example
+++ b/.env.example
@ -19,10 +19,12 @@
 # HOSTNAME=your-hostname

 # 数据库相关配置
-# 启用错误日志记录
-# ERROR_LOG_ENABLED=true
 # 数据库连接字符串
 # SQL_DSN=user:password@tcp(127.0.0.1:3306)/dbname?parseTime=true
+# Host process profile on infra host:
+# SQL_DSN=postgresql://root:example-password@127.0.0.1:5433/new-api
+# Docker profile on same host:
+# SQL_DSN=postgresql://root:example-password@infra-postgres:5432/new-api
 # 日志数据库连接字符串
 # LOG_SQL_DSN=user:password@tcp(127.0.0.1:3306)/logdb?parseTime=true
 # SQLite数据库路径
@ -38,6 +40,10 @@
 # 缓存相关配置
 # Redis连接字符串
 # REDIS_CONN_STRING=redis://user:password@localhost:6379/0
+# Host process profile on infra host:
+# REDIS_CONN_STRING=redis://:example-password@127.0.0.1:6379/0
+# Docker profile on same host:
+# REDIS_CONN_STRING=redis://:example-password@infra-redis:6379/0
 # 同步频率（单位：秒）
 # SYNC_FREQUENCY=60
 # 内存缓存启用
--- a/AGENTS.md
+++ b/AGENTS.md
@ -135,3 +135,20 @@ For request structs that are parsed from client JSON and then re-marshaled to up
 ### Rule 7: Billing Expression System — Read `pkg/billingexpr/expr.md`

 When working on tiered/dynamic billing (expression-based pricing), you MUST read `pkg/billingexpr/expr.md` first. It documents the design philosophy, expression language (variables, functions, examples), full system architecture (editor → storage → pre-consume → settlement → log display), token normalization rules (`p`/`c` auto-exclusion), quota conversion, and expression versioning. All code changes to the billing expression system must follow the patterns described in that document.
+
+
+# 项目运维与排障
+
+排障记录、远程布局、部署流程详见 `CLAUDE.md` 底部"项目排障记录"章节。
+
+## Git 远程角色布局
+
+| 远程 | URL | 角色 |
+|------|-----|------|
+| `upstream` | `https://github.com/QuantumNous/new-api.git` | 官方上游（只读） |
+| `gitea` | `ssh://git@100.64.0.8:2222/admin/new-api-dev.git` | 读-only 开发镜像 |
+| `ea-ali` | `ssh://git@101.200.34.71:2222/zizi-al/new-api.git` | 可写开发远程（默认 push） |
+
+## 远程运行事实入口
+
+具体远程部署、主机拓扑、端口、备份、Gitea 运行方式等，统一收口到 `ops/remote/` 下对应主机文档。不要往项目根文档追加主机级流水账。
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -135,3 +135,59 @@ For request structs that are parsed from client JSON and then re-marshaled to up
 ### Rule 7: Billing Expression System — Read `pkg/billingexpr/expr.md`

 When working on tiered/dynamic billing (expression-based pricing), you MUST read `pkg/billingexpr/expr.md` first. It documents the design philosophy, expression language (variables, functions, examples), full system architecture (editor → storage → pre-consume → settlement → log display), token normalization rules (`p`/`c` auto-exclusion), quota conversion, and expression versioning. All code changes to the billing expression system must follow the patterns described in that document.
+
+
+# new-api 项目排障记录
+
+## 排障原则
+- 不要先改 Docker 配置，先查数据库表：`channels`、`abilities`、`options`
+- 不要因为代码默认值存在，就假定线上有效
+- 遇到"倍率或价格未配置"时，优先检查：`options.ModelRatio`、`options.ModelPrice`
+- 遇到渠道测试失败时，先分清：上游不通 vs 服务端计费配置缺失
+- 代码里有默认倍率，但线上运行时会被数据库 `options.ModelRatio` 覆盖
+- `new-api` 会定时从数据库同步 `options` 和 `channels`，不需要每次重启；日志关键字：`syncing options from database`
+
+## 依赖服务与连接方式
+- PostgreSQL 和 Redis 是共享基础设施，不属于 `new-api` 仓库内嵌部署的一部分
+- 宿主机进程模式固定入口：PostgreSQL `127.0.0.1:5433`、Redis `127.0.0.1:6379`
+- 同宿主机 Docker 模式固定入口：PostgreSQL `infra-postgres:5432`、Redis `infra-redis:6379`
+
+## 运维入口与排障顺序
+- `new-api` 健康检查：`curl http://127.0.0.1:3000/api/status`
+- 基础设施排障：`docker ps | grep -E 'infra-postgres|infra-redis|gitea'`
+
+## Git 远程角色布局（2026-05-18 更新）
+
+| 远程 | URL | 角色 | 备注 |
+|------|-----|------|------|
+| `upstream` | `https://github.com/QuantumNous/new-api.git` | 官方上游 | 只读，fetch only |
+| `gitea` | `ssh://git@100.64.0.8:2222/admin/new-api-dev.git` | 读-only 开发镜像 | push 已禁用（`no-push`） |
+| `ea-ali` | `ssh://git@101.200.34.71:2222/zizi-al/new-api.git` | 可写开发远程 | `remote.pushDefault` 指向此 |
+
+代码流向：`upstream` → 本地 → `gitea`（镜像同步）→ 本地 → `ea-ali`（二开推送）
+
+- `ea-ali` 服务器无法访问 `100.64.0.8`，同步必须经本地中转
+- 当前开发分支：`dev/1.0.0`，跟踪 `ea-ali/dev/1.0.0`
+
+## 本地编译 Docker 部署流程（2026-05-18 新增）
+
+本地开发 → 本地 Docker 构建 → 上传镜像 → 远程 Docker 部署。
+
+```bash
+# 1. 本地构建
+docker build -t new-api:local .
+
+# 2. 导出
+docker save new-api:local | gzip > /tmp/new-api-local.tar.gz
+
+# 3. 上传到远程
+scp /tmp/new-api-local.tar.gz root@<remote-host>:/tmp/
+
+# 4. 远程加载
+ssh root@<remote-host> "docker load < /tmp/new-api-local.tar.gz"
+
+# 5. 远程重启
+ssh root@<remote-host> "cd /opt/new-api && docker compose up -d"
+```
+
+镜像 tag 建议带版本号：`new-api:1.0.0-dev`、`new-api:1.0.0-rc1`。
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 <div align="center">

-![new-api](/web/default/public/logo.png)
+![new-api](/web/public/logo.png)

 # New API

@ -55,10 +55,9 @@
 ## 📝 Project Description

 > [!IMPORTANT]
-> - This project is intended solely for lawful and authorized AI API gateway, organization-level authentication, multi-model management, usage analytics, cost accounting, and private deployment scenarios.
-> - Users must lawfully obtain upstream API keys, accounts, model services, and interface permissions, and must comply with upstream terms of service and applicable laws and regulations.
-> - Users should ensure their use complies with upstream terms of service and applicable laws and regulations.
-> - When providing generative AI services to the public, users should comply with applicable regulatory requirements and fulfill all filing, licensing, content safety, real-name verification, log retention, tax, and upstream authorization obligations required by their jurisdiction.
+> - This project is for personal learning purposes only, with no guarantee of stability or technical support
+> - Users must comply with OpenAI's [Terms of Use](https://openai.com/policies/terms-of-use) and **applicable laws and regulations**, and must not use it for illegal purposes
+> - According to the [《Interim Measures for the Management of Generative Artificial Intelligence Services》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm), please do not provide any unregistered generative AI services to the public in China.

 ---

@ -107,18 +106,37 @@

 ## 🚀 Quick Start

-### Using Docker Compose (Recommended)
+### Using Docker Compose

 ```bash
 # Clone the project
 git clone https://github.com/QuantumNous/new-api.git
 cd new-api

-# Edit docker-compose.yml configuration
-nano docker-compose.yml
+# Copy environment template
+cp .env.example .env.runtime
+
+# Edit SQL_DSN and REDIS_CONN_STRING for your runtime profile
+nano .env.runtime

 # Start the service
-docker-compose up -d
+docker compose --env-file .env.runtime up -d
+```
+
+This compose file is app-only. PostgreSQL and Redis are expected to be external shared infrastructure.
+
+Host process profile on the infra host:
+
+```bash
+SQL_DSN=postgresql://root:${POSTGRES_PASSWORD}@127.0.0.1:5433/new-api
+REDIS_CONN_STRING=redis://:${REDIS_PASSWORD}@127.0.0.1:6379/0
+```
+
+Docker profile on the same host:
+
+```bash
+SQL_DSN=postgresql://root:${POSTGRES_PASSWORD}@infra-postgres:5432/new-api
+REDIS_CONN_STRING=redis://:${REDIS_PASSWORD}@infra-redis:6379/0
 ```

 <details>
@ -152,9 +170,6 @@ docker run --name new-api -d --restart always \

 🎉 After deployment is complete, visit `http://localhost:3000` to start using!

-> [!WARNING]
-> When operating this project as a public generative AI service or API resale service, users should first complete all required filing, licensing, content safety, real-name verification, log retention, tax, payment, and upstream authorization obligations.
-
 📖 For more deployment methods, please refer to [Deployment Guide](https://docs.newapi.pro/en/docs/installation)

 ---
@ -193,12 +208,12 @@ docker run --name new-api -d --restart always \
 | 📈 Data Dashboard | Visual console and statistical analysis |
 | 🔒 Permission Management | Token grouping, model restrictions, user management |

-### 💰 Authorized Usage Accounting and Billing
+### 💰 Payment and Billing

- ✅ Internal top-up and quota allocation for lawful authorized scenarios (EPay, Stripe)
- ✅ Organization-level per-request, usage-based, and cache-hit cost accounting
- ✅ Cache billing statistics for OpenAI, Azure, DeepSeek, Claude, Qwen, and supported models
- ✅ Flexible billing policies for internal management or authorized enterprise customers
+- ✅ Online recharge (EPay, Stripe)
+- ✅ Pay-per-use model pricing
+- ✅ Cache billing support (OpenAI, Azure, DeepSeek, Claude, Qwen and all supported models)
+- ✅ Flexible billing policy configuration

 ### 🔐 Authorization and Security

@ -206,7 +221,7 @@ docker run --name new-api -d --restart always \
 - 🤖 LinuxDO authorization login
 - 📱 Telegram authorization login
 - 🔑 OIDC unified authentication
- 🔍 Key quota query usage (with [new-api-key-tool](https://github.com/Calcium-Ion/new-api-key-tool))
+- 🔍 Key quota query usage (with [neko-api-key-tool](https://github.com/Calcium-Ion/neko-api-key-tool))

 ### 🚀 Advanced Features

@ -258,7 +273,7 @@ docker run --name new-api -d --restart always \

 ## 🤖 Model Support

-> For details, please refer to [API Documentation - Gateway Interface](https://docs.newapi.pro/en/docs/api)
+> For details, please refer to [API Documentation - Relay Interface](https://docs.newapi.pro/en/docs/api)

 | Model Type | Description | Documentation |
 |---------|------|------|
@ -270,7 +285,7 @@ docker run --name new-api -d --restart always \
 | 💬 Claude | Messages format | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/createmessage) |
 | 🌐 Gemini | Google Gemini format | [Documentation](https://docs.newapi.pro/en/docs/api/ai-model/chat/gemini/geminirelayv1beta) |
 | 🔧 Dify | ChatFlow mode | - |
-| 🎯 Custom upstream | Supports configuring legally authorized upstream endpoints | - |
+| 🎯 Custom | Supports complete call address | - |

 ### 📡 Supported Interfaces

@ -314,8 +329,8 @@ docker run --name new-api -d --restart always \
 |--------|------|--------|
 | `SESSION_SECRET` | Session secret (required for multi-machine deployment) | - |
 | `CRYPTO_SECRET` | Encryption secret (required for Redis) | - |
-| `SQL_DSN` | Database connection string | - |
-| `REDIS_CONN_STRING` | Redis connection string | - |
+| `SQL_DSN` | Database connection string. Use `127.0.0.1:5433` for host mode or `infra-postgres:5432` for same-host Docker mode | - |
+| `REDIS_CONN_STRING` | Redis connection string. Use `127.0.0.1:6379` for host mode or `infra-redis:6379` for same-host Docker mode | - |
 | `STREAMING_TIMEOUT` | Streaming timeout (seconds) | `300` |
 | `STREAM_SCANNER_MAX_BUFFER_MB` | Max per-line buffer (MB) for the stream scanner; increase when upstream sends huge image/base64 payloads | `64` |
 | `MAX_REQUEST_BODY_MB` | Max request body size (MB, counted **after decompression**; prevents huge requests/zip bombs from exhausting memory). Exceeding it returns `413` | `32` |
@ -420,7 +435,7 @@ docker run --name new-api -d --restart always \

 | Project | Description |
 |------|------|
-| [new-api-key-tool](https://github.com/Calcium-Ion/new-api-key-tool) | Key quota query tool |
+| [neko-api-key-tool](https://github.com/Calcium-Ion/neko-api-key-tool) | Key quota query tool |
 | [new-api-horizon](https://github.com/Calcium-Ion/new-api-horizon) | New API high-performance optimized version |

 ---
@ -451,14 +466,6 @@ Welcome all forms of contribution!

 This project is licensed under the [GNU Affero General Public License v3.0 (AGPLv3)](./LICENSE).

-Additional terms under AGPLv3 Section 7 apply. Modified versions must preserve
-the author attribution notice `Frontend design and development by New API
-contributors.` in the appropriate legal notices and in any prominent about,
-legal, footer, or attribution location presented by the user interface.
-
-Modified versions that present a user interface must also preserve a visible
-link to the original project: <https://github.com/QuantumNous/new-api>.
-
 This is an open-source project developed based on [One API](https://github.com/songquanpeng/one-api) (MIT License).

 If your organization's policies do not permit the use of AGPLv3-licensed software, or if you wish to avoid the open-source obligations of AGPLv3, please contact us at: [support@quantumnous.com](mailto:support@quantumnous.com)
--- a/README.zh_CN.md
+++ b/README.zh_CN.md
@ -1,6 +1,6 @@
 <div align="center">

-![new-api](/web/default/public/logo.png)
+![new-api](/web/public/logo.png)

 # New API

@ -55,10 +55,9 @@
 ## 📝 项目说明

 > [!IMPORTANT]
-> - 本项目仅面向合法授权的 AI API 网关、组织内部鉴权、多模型管理、用量统计、成本核算和私有化部署场景。
-> - 使用者必须合法取得上游 API Key、账号、模型服务或接口权限，并遵守上游服务条款及适用法律法规。
-> - 使用者应确保其使用方式符合上游服务条款及适用法律法规。
-> - 面向公众提供生成式人工智能服务时，使用者应遵守[《生成式人工智能服务管理暂行办法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)等监管要求，自行完成所在司法辖区要求的备案、许可、内容安全、实名、日志留存、税务和上游授权等合规义务。
+> - 本项目仅供个人学习使用，不保证稳定性，且不提供任何技术支持
+> - 使用者必须在遵循 OpenAI 的 [使用条款](https://openai.com/policies/terms-of-use) 以及**法律法规**的情况下使用，不得用于非法用途
+> - 根据 [《生成式人工智能服务管理暂行办法》](http://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm) 的要求，请勿对中国地区公众提供一切未经备案的生成式人工智能服务

 ---

@ -107,18 +106,37 @@

 ## 🚀 快速开始

-### 使用 Docker Compose（推荐）
+### 使用 Docker Compose

 ```bash
 # 克隆项目
 git clone https://github.com/QuantumNous/new-api.git
 cd new-api

-# 编辑 docker-compose.yml 配置
-nano docker-compose.yml
+# 复制环境变量模板
+cp .env.example .env.runtime
+
+# 按运行模式填写 SQL_DSN 和 REDIS_CONN_STRING
+nano .env.runtime

 # 启动服务
-docker-compose up -d
+docker compose --env-file .env.runtime up -d
+```
+
+当前 `docker-compose.yml` 只负责应用本体，PostgreSQL 和 Redis 应作为外部共享基础设施提供。
+
+宿主机进程模式：
+
+```bash
+SQL_DSN=postgresql://root:${POSTGRES_PASSWORD}@127.0.0.1:5433/new-api
+REDIS_CONN_STRING=redis://:${REDIS_PASSWORD}@127.0.0.1:6379/0
+```
+
+同宿主机 Docker 模式：
+
+```bash
+SQL_DSN=postgresql://root:${POSTGRES_PASSWORD}@infra-postgres:5432/new-api
+REDIS_CONN_STRING=redis://:${REDIS_PASSWORD}@infra-redis:6379/0
 ```

 <details>
@ -152,9 +170,6 @@ docker run --name new-api -d --restart always \

 🎉 部署完成后，访问 `http://localhost:3000` 即可使用！

-> [!WARNING]
-> 将本项目作为面向公众的生成式 AI 服务或 API 转售服务运营时，使用者应先完成备案、内容安全、实名、日志留存、税务、支付和上游授权等合规义务。
-
 📖 更多部署方式请参考 [部署指南](https://docs.newapi.pro/zh/docs/installation)

 ---
@ -193,12 +208,12 @@ docker run --name new-api -d --restart always \
 | 📈 数据看板 | 可视化控制台与统计分析 |
 | 🔒 权限管理 | 令牌分组、模型限制、用户管理 |

-### 💰 授权用量与成本管理
+### 💰 支付与计费

- ✅ 合法授权场景下的内部充值与额度分配（易支付、Stripe）
- ✅ 组织内按次、按量或缓存命中成本核算
- ✅ 支持 OpenAI、Azure、DeepSeek、Claude、Qwen 等模型的缓存计费统计
- ✅ 面向内部管理或企业客户的灵活计费策略配置
+- ✅ 在线充值（易支付、Stripe）
+- ✅ 模型按次数收费
+- ✅ 缓存计费支持（OpenAI、Azure、DeepSeek、Claude、Qwen等所有支持的模型）
+- ✅ 灵活的计费策略配置

 ### 🔐 授权与安全

@ -206,7 +221,7 @@ docker run --name new-api -d --restart always \
 - 🤖 LinuxDO 授权登录
 - 📱 Telegram 授权登录
 - 🔑 OIDC 统一认证
- 🔍 Key 查询使用额度（配合 [new-api-key-tool](https://github.com/Calcium-Ion/new-api-key-tool)）
+- 🔍 Key 查询使用额度（配合 [neko-api-key-tool](https://github.com/Calcium-Ion/neko-api-key-tool)）

 ### 🚀 高级功能

@ -258,7 +273,7 @@ docker run --name new-api -d --restart always \

 ## 🤖 模型支持

-> 详情请参考 [接口文档 - 网关接口](https://docs.newapi.pro/zh/docs/api)
+> 详情请参考 [接口文档 - 中继接口](https://docs.newapi.pro/zh/docs/api)

 | 模型类型 | 说明 | 文档 |
 |---------|------|------|
@ -270,7 +285,7 @@ docker run --name new-api -d --restart always \
 | 💬 Claude | Messages 格式 | [文档](https://docs.newapi.pro/zh/docs/api/ai-model/chat/createmessage) |
 | 🌐 Gemini | Google Gemini 格式 | [文档](https://docs.newapi.pro/zh/docs/api/ai-model/chat/gemini/geminirelayv1beta) |
 | 🔧 Dify | ChatFlow 模式 | - |
-| 🎯 自定义上游 | 支持配置合法授权的上游接口地址 | - |
+| 🎯 自定义 | 支持完整调用地址 | - |

 ### 📡 支持的接口

@ -314,8 +329,8 @@ docker run --name new-api -d --restart always \
 |--------|--------------------------------------------------------------|--------|
 | `SESSION_SECRET` | 会话密钥（多机部署必须）                                                 | - |
 | `CRYPTO_SECRET` | 加密密钥（Redis 必须）                                               | - |
-| `SQL_DSN` | 数据库连接字符串                                                     | - |
-| `REDIS_CONN_STRING` | Redis 连接字符串                                                  | - |
+| `SQL_DSN` | 数据库连接字符串。宿主机模式使用 `127.0.0.1:5433`，同宿主机 Docker 模式使用 `infra-postgres:5432` | - |
+| `REDIS_CONN_STRING` | Redis 连接字符串。宿主机模式使用 `127.0.0.1:6379`，同宿主机 Docker 模式使用 `infra-redis:6379` | - |
 | `STREAMING_TIMEOUT` | 流式超时时间（秒）                                                    | `300` |
 | `STREAM_SCANNER_MAX_BUFFER_MB` | 流式扫描器单行最大缓冲（MB），图像生成等超大 `data:` 片段（如 4K 图片 base64）需适当调大 | `64` |
 | `MAX_REQUEST_BODY_MB` | 请求体最大大小（MB，**解压后**计；防止超大请求/zip bomb 导致内存暴涨），超过将返回 `413` | `32` |
@ -420,7 +435,7 @@ docker run --name new-api -d --restart always \

 | 项目 | 说明 |
 |------|------|
-| [new-api-key-tool](https://github.com/Calcium-Ion/new-api-key-tool) | Key 额度查询工具 |
+| [neko-api-key-tool](https://github.com/Calcium-Ion/neko-api-key-tool) | Key 额度查询工具 |
 | [new-api-horizon](https://github.com/Calcium-Ion/new-api-horizon) | New API 高性能优化版 |

 ---
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -1,19 +1,3 @@
-# New-API Docker Compose Configuration
-# 
-# Quick Start:
-#   1. docker-compose up -d
-#   2. Access at http://localhost:3000
-#
-# Using MySQL instead of PostgreSQL:
-#   1. Comment out the postgres service and SQL_DSN line 15
-#   2. Uncomment the mysql service and SQL_DSN line 16
-#   3. Uncomment mysql in depends_on (line 28)
-#   4. Uncomment mysql_data in volumes section (line 64)
-#
-# ⚠️  IMPORTANT: Change all default passwords before deploying to production!
-
-version: '3.4' # For compatibility with older Docker versions
-
 services:
  new-api:
    image: calciumion/new-api:latest
@ -26,73 +10,21 @@ services:
      - ./data:/data
      - ./logs:/app/logs
    environment:
-      - SQL_DSN=postgresql://root:123456@postgres:5432/new-api # ⚠️ IMPORTANT: Change the password in production!
-#      - SQL_DSN=root:123456@tcp(mysql:3306)/new-api  # Point to the mysql service, uncomment if using MySQL
-      - REDIS_CONN_STRING=redis://:123456@redis:6379 # ⚠️ IMPORTANT: Change the password in production!
-      - TZ=Asia/Shanghai
-      - ERROR_LOG_ENABLED=true # 是否启用错误日志记录 (Whether to enable error log recording)
-      - BATCH_UPDATE_ENABLED=true  # 是否启用批量更新 (Whether to enable batch update)
-      - NODE_NAME=new-api-node-1  # 节点名称，用于审计日志中标识节点身份；多节点/容器部署时建议设置 (Node name used in audit logs; recommended when running multiple instances or in containers)
-#      - STREAMING_TIMEOUT=300  # 流模式无响应超时时间，单位秒，默认120秒，如果出现空补全可以尝试改为更大值 （Streaming timeout in seconds, default is 120s. Increase if experiencing empty completions）
-#      - SESSION_SECRET=random_string  # 多机部署时设置，必须修改这个随机字符串！！ （multi-node deployment, set this to a random string!!!!!!!）
-#      - SYNC_FREQUENCY=60  # Uncomment if regular database syncing is needed
-#      - GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX  # Google Analytics 的测量 ID (Google Analytics Measurement ID)
-#      - UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  # Umami 网站 ID (Umami Website ID)
-#      - UMAMI_SCRIPT_URL=https://analytics.umami.is/script.js  # Umami 脚本 URL，默认为官方地址 (Umami Script URL, defaults to official URL)
-
-    depends_on:
-      - redis
-      - postgres
-#      - mysql  # Uncomment if using MySQL
+      SQL_DSN: ${SQL_DSN:?SQL_DSN is required}
+      REDIS_CONN_STRING: ${REDIS_CONN_STRING:?REDIS_CONN_STRING is required}
+      TZ: ${TZ:-Asia/Shanghai}
+      ERROR_LOG_ENABLED: ${ERROR_LOG_ENABLED:-true}
+      BATCH_UPDATE_ENABLED: ${BATCH_UPDATE_ENABLED:-true}
    networks:
-      - new-api-network
+      - default
+      - infra-shared
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

-  redis:
-    image: redis:latest
-    container_name: redis
-    restart: always
-    command: ["redis-server", "--requirepass", "123456"]  # ⚠️ IMPORTANT: Change this password in production!
-    networks:
-      - new-api-network
-
-  postgres:
-    image: postgres:15
-    container_name: postgres
-    restart: always
-    environment:
-      POSTGRES_USER: root
-      POSTGRES_PASSWORD: 123456  # ⚠️ IMPORTANT: Change this password in production!
-      POSTGRES_DB: new-api
-    volumes:
-      - pg_data:/var/lib/postgresql/data
-    networks:
-      - new-api-network
-#    ports:
-#      - "5432:5432"  # Uncomment if you need to access PostgreSQL from outside Docker
-
-#  mysql:
-#    image: mysql:8.2
-#    container_name: mysql
-#    restart: always
-#    environment:
-#      MYSQL_ROOT_PASSWORD: 123456  # ⚠️ IMPORTANT: Change this password in production!
-#      MYSQL_DATABASE: new-api
-#    volumes:
-#      - mysql_data:/var/lib/mysql
-#    networks:
-#      - new-api-network
-#    ports:
-#      - "3306:3306"  # Uncomment if you need to access MySQL from outside Docker
-
-volumes:
-  pg_data:
-#  mysql_data:
-
 networks:
-  new-api-network:
-    driver: bridge
+  infra-shared:
+    external: true
+    name: infra-shared
--- a/ops/remote/GIT_GITEA.AGENT.md
+++ b/ops/remote/GIT_GITEA.AGENT.md
@ -0,0 +1,363 @@
+# Git and Gitea Management AGENT
+
+## Purpose
+
+This document defines the canonical workflow for managing:
+
+- local Git repositories
+- GitHub upstream repositories
+- writable Gitea repositories
+- read-only Gitea mirror repositories
+
+This file exists to prevent remote confusion, mirror misuse, and branch history corruption.
+
+## 1. Core Principles
+
+### 1.1 One repo, one role
+Do not let a single remote repository play multiple conflicting roles.
+
+A repository should be clearly one of:
+
+- upstream source
+- writable development remote
+- read-only mirror
+
+If a repository is a mirror, treat it as a mirror.
+If a repository is writable, treat it as writable.
+Do not mix the two.
+
+### 1.2 Never confuse source of truth
+The source of truth for official upstream code is the upstream repository, not the writable Gitea dev repo, and not the mirror.
+
+### 1.3 Keep `main` clean
+`main` is for syncing upstream only.
+Do not pile local feature work directly into `main`.
+
+### 1.4 Local changes belong on dev branches
+Local work belongs on branches like:
+
+- `home`
+- `feature/*`
+- `fix/*`
+
+Do not treat the mirror repo as a development target.
+
+## 2. Remote Roles
+
+### 2.1 Canonical remote names
+Use these exact names:
+
+- `upstream` — official upstream source repository
+- `gitea` — writable development repository on Gitea
+
+Do not rename them casually.
+
+### 2.2 Role definitions
+
+#### `upstream`
+Used only for:
+
+- fetching latest official code
+- comparing branch divergence
+- updating local `main`
+
+Example:
+
+- `upstream -> https://github.com/QuantumNous/new-api.git`
+
+#### `gitea`
+Used only for:
+
+- pushing local branches
+- opening PRs on writable Gitea repos
+- storing development work
+
+Example:
+
+- `gitea -> ssh://git@100.64.0.8:2222/admin/new-api-dev.git`
+
+#### Read-only mirror repo
+If a Gitea repo is configured as a pull mirror, it is read-only for development purposes.
+
+Example:
+
+- `admin/new-api` is a pull mirror of GitHub
+- it is for sync / reference / backup
+- it is not the target for normal pushes
+
+Do not point `gitea` to a mirror repo.
+
+## 3. Required Repository Topology
+
+For projects that track an open-source upstream and also need private or self-hosted development:
+
+- one upstream repo
+- one writable Gitea dev repo
+- optional one Gitea mirror repo
+
+Recommended shape:
+
+- `upstream` -> official GitHub repo
+- `gitea` -> writable Gitea repo
+- optional mirror repo exists separately but is not the main local push target
+
+## 4. Branch Responsibilities
+
+### `main`
+Responsibilities:
+
+- track upstream
+- remain linear and clean
+- only accept upstream sync commits or fast-forward updates
+
+Rules:
+
+- do not do feature development directly on `main`
+- do not use `main` as a scratch branch
+- prefer `merge --ff-only` when updating from upstream
+
+### `home`
+Responsibilities:
+
+- personal development branch
+- local operational or infrastructure work
+- custom changes that do not belong on clean upstream `main`
+
+Rules:
+
+- rebase or merge onto updated `main`
+- push to writable Gitea repo
+- do not track upstream directly
+
+### `feature/*`
+Responsibilities:
+
+- isolated work branches
+- short-lived development branches
+- branch off from current `main` or from `home` when appropriate
+
+## 5. Standard Workflow
+
+### 5.1 Inspect repository state
+Always inspect first:
+
+```bash
+git remote -v
+git branch -vv
+git status --short
+```
+
+If remotes or tracking look wrong, fix them before pushing.
+
+### 5.2 Sync local `main` with upstream
+Preferred flow:
+
+```bash
+git fetch upstream
+git switch main
+git merge --ff-only upstream/main
+git push gitea main
+```
+
+This keeps:
+
+- local `main`
+- writable Gitea `main`
+
+aligned with upstream.
+
+### 5.3 Update development branch after upstream sync
+If using rebase:
+
+```bash
+git switch home
+git rebase main
+git push --force-with-lease gitea home
+```
+
+If using merge:
+
+```bash
+git switch home
+git merge main
+git push gitea home
+```
+
+Use `rebase` when clean linear history matters.
+Use `merge` when you do not want history rewriting.
+
+### 5.4 Create a new working branch
+From updated `main`:
+
+```bash
+git switch main
+git switch -c feature/<name>
+```
+
+Push it:
+
+```bash
+git push -u gitea feature/<name>
+```
+
+### 5.5 Push local changes
+Always push to writable Gitea repo:
+
+```bash
+git push gitea <branch>
+```
+
+Do not push to mirror repos.
+
+## 6. Fallback Workflow When GitHub Is Unreachable
+
+If local machine cannot access GitHub, but the Gitea mirror is confirmed fresh, the mirror may be used as a temporary fetch source.
+
+Example:
+
+```bash
+git fetch ssh://git@100.64.0.8:2222/admin/new-api.git refs/heads/main:refs/remotes/upstream/main
+git switch main
+git merge --ff-only upstream/main
+git push gitea main
+```
+
+### Important restriction
+Do this only after verifying that the mirror really matches upstream.
+
+Check both sides:
+
+- GitHub main commit
+- Gitea mirror main commit
+
+If they differ, do not use the mirror as a substitute for upstream.
+
+## 7. Gitea Mirror Rules
+
+If a Gitea repository is a pull mirror:
+
+- it is a sync target, not a dev target
+- pushes may fail or be meaningless
+- it should be treated as read-only for development
+
+Use mirror repos for:
+
+- backup
+- browsing
+- clone acceleration
+- temporary upstream fallback when verified fresh
+
+Do not use mirror repos for:
+
+- long-term feature branch work
+- main development push target
+- authoritative branch ownership
+
+## 8. SSH Rules for Gitea
+
+Use Gitea built-in SSH, not random container SSH assumptions.
+
+Example working clone form:
+
+```bash
+git clone ssh://git@100.64.0.8:2222/admin/new-api-dev.git
+```
+
+If SSH suddenly breaks after a server-side SSH mapping change:
+
+- verify host port mapping
+- verify Gitea built-in SSH port
+- refresh local `known_hosts` if host key changed
+
+Example:
+
+```bash
+ssh-keygen -R '[100.64.0.8]:2222'
+ssh -T -p 2222 git@100.64.0.8
+```
+
+## 9. Required Remote Configuration for This Project
+
+Current expected shape:
+
+- `upstream` -> official GitHub repository
+- `gitea` -> writable Gitea development repository
+
+Expected result style:
+
+```text
+gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (fetch)
+gitea    ssh://git@100.64.0.8:2222/admin/new-api-dev.git (push)
+upstream https://github.com/QuantumNous/new-api.git (fetch)
+upstream https://github.com/QuantumNous/new-api.git (push)
+```
+
+Expected tracking style:
+
+- `main` -> `upstream/main`
+- `home` -> `gitea/home`
+
+## 10. Forbidden Operations
+
+Do not do the following unless you explicitly know why:
+
+- push local feature work into a pull mirror repo
+- remove `upstream` and pretend Gitea mirror is always equal to GitHub
+- develop directly on `main`
+- rewrite shared branch history without understanding the impact
+- force-push `main`
+- use mirror repos as the only source of upstream truth
+- change remote roles casually
+
+## 11. Minimal Recovery Rules
+
+If repository roles become confused:
+
+1. inspect remotes
+2. identify which repo is writable and which is mirrored
+3. restore:
+   - `upstream` -> official source
+   - `gitea` -> writable dev repo
+4. restore tracking:
+   - `main` -> `upstream/main`
+   - dev branch -> `gitea/<branch>`
+
+Useful commands:
+
+```bash
+git remote -v
+git branch -vv
+git config --get branch.main.remote
+git config --get branch.main.merge
+git config --get remote.pushDefault
+```
+
+## 12. Recommended Defaults
+
+Set default push target to writable Gitea:
+
+```bash
+git config remote.pushDefault gitea
+```
+
+Set `main` tracking to upstream:
+
+```bash
+git branch --set-upstream-to=upstream/main main
+```
+
+Set dev branch tracking to Gitea:
+
+```bash
+git branch --set-upstream-to=gitea/home home
+```
+
+## 13. Human Rule
+
+If you cannot explain, in one sentence, which remote is:
+
+- official upstream
+- writable dev remote
+- mirror
+
+then stop and fix the repository configuration before doing more Git work.
--- a/ops/remote/README.md
+++ b/ops/remote/README.md
@ -0,0 +1,9 @@
+# Remote Runtime Notes
+
+这个目录记录远程主机运行事实，避免把主机级流水账继续堆回根文档。
+
+约定：
+
+- 一台主机一份 `*.AGENT.md`
+- 只写运行事实、入口、路径、端口、依赖和排障命令
+- 项目规则仍放在根 `AGENTS.md` / `CLAUDE.md`
--- a/ops/remote/TEMPLATE.AGENT.md
+++ b/ops/remote/TEMPLATE.AGENT.md
@ -0,0 +1,73 @@
+# Remote Host AGENT Template
+
+## 1. Host Identity
+- Host name:
+- Host role:
+- Region or environment:
+- Primary access path:
+- Tailscale IP:
+- Other important IPs or domains:
+
+## 2. Access and Safety
+- SSH profile or connection method:
+- Primary operator:
+- Privilege model:
+- Proxy requirements:
+- Secrets location:
+- Important do-not-touch items:
+
+## 3. Runtime Topology
+- Main deployment styles on this host:
+- Shared Docker networks:
+- Shared databases or caches:
+- Host-level ports in use:
+- Reverse proxy or ingress layer:
+
+## 4. Project Inventory
+
+### Project: <name>
+- Purpose:
+- Deploy mode:
+- Runtime entrypoint:
+- Source repo path:
+- Runtime directory:
+- Main service or container names:
+- Public or internal endpoints:
+- Config files:
+- Data location:
+- Backup location:
+- Logs and inspection commands:
+- Upgrade path:
+- Known traps:
+
+## 5. Git and Repository Strategy
+- Writable repositories:
+- Mirror repositories:
+- Upstream repositories:
+- Default push targets:
+- Branch strategy:
+- Sync workflow:
+
+## 6. Data and Backup
+- Databases in use:
+- Named volumes or bind mounts:
+- Backup commands:
+- Restore notes:
+- High-risk destructive actions to avoid:
+
+## 7. Routine Operations
+- Check health:
+- Check logs:
+- Restart service:
+- Restart containers:
+- Verify ports:
+- Verify external access:
+
+## 8. Incident Notes
+- Recent incidents:
+- Root causes found:
+- Permanent fixes applied:
+- Remaining risks:
+
+## 9. Change Log
+- YYYY-MM-DD: <what changed>
--- a/ops/remote/minione-ubuntu-infra-4c16g120g.AGENT.md
+++ b/ops/remote/minione-ubuntu-infra-4c16g120g.AGENT.md
@ -0,0 +1,63 @@
+# Remote Host AGENT — minione-ubuntu-infra-4c16g120g
+
+## Host Identity
+
+- Host name: `minione-ubuntu-infra`
+- Tailscale IP: `100.64.0.8`
+- LAN IP: `192.168.1.3`
+- Access profile: `个人-minione-ubuntu-infra-4c16g120g`
+
+## Runtime Topology
+
+- `new-api` runs as a host `systemd` process
+- `gitea` runs in Docker Compose under `/opt/gitea`
+- PostgreSQL and Redis run as shared Docker infrastructure
+- Shared Docker network: `infra-shared`
+
+## Shared Infrastructure
+
+### PostgreSQL
+
+- Container name: `infra-postgres`
+- Host port: `127.0.0.1:5433`
+- Docker alias: `infra-postgres:5432`
+- Databases:
+  - `new-api`
+  - `gitea`
+- Data path: `/srv/infra/postgres/data`
+- Backup path: `/srv/infra/postgres/backup`
+
+### Redis
+
+- Container name: `infra-redis`
+- Host port: `127.0.0.1:6379`
+- Docker alias: `infra-redis:6379`
+- Data path: `/srv/infra/redis/data`
+
+## new-api
+
+- Service name: `new-api`
+- Deploy path: `/root/new-api-deploy`
+- Runtime env: `/root/new-api-deploy/.env.runtime`
+- systemd unit: `/etc/systemd/system/new-api.service`
+- Health check: `curl --noproxy '*' http://127.0.0.1:3000/api/status`
+
+Host-process connection profile:
+
+- `SQL_DSN=postgresql://root:<password>@127.0.0.1:5433/new-api`
+- `REDIS_CONN_STRING=redis://:<password>@127.0.0.1:6379/0`
+
+## gitea
+
+- Compose path: `/opt/gitea/docker-compose.yml`
+- Config path: `/opt/gitea/data/gitea/conf/app.ini`
+- Web: `http://100.64.0.8:3001/`
+- SSH: `ssh -p 2222 git@100.64.0.8`
+- Database host: `infra-postgres:5432`
+
+## Routine Checks
+
+- `systemctl status new-api`
+- `journalctl -u new-api -n 200 --no-pager`
+- `docker ps --format '{{.Names}} | {{.Image}} | {{.Ports}}'`
+- `ss -lntp | egrep ':3000|:3001|:2222|:5433|:6379'`