diff --git a/INSTALL.md b/INSTALL.md
index bd510061..74a54bda 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,573 +1,375 @@
-### 安装说明
-
-
-### 方式一. 手动安装（推荐）
-
-克隆代码库
-
-   ```sh
-   git clone https://github.com/rocboss/paopao-ce.git
-   ```
-
-#### 后端
-
-1. 导入项目根目录下的 `scripts/paopao.sql` 文件至MySQL数据库
-2. 拷贝项目根目录下 `config.yaml.sample` 文件至 `config.yaml`，按照注释完成配置编辑
-3. 编译后端    
-    编译api服务:
-    ```sh
-    make build
-    ```
-    编译api服务、内嵌web前端ui:
-    ```sh
-    make build
-    ```
-    也可以使用精简模式编译，不内嵌web前端ui:
-    ```sh
-    make build TAGS='slim embed'
-    ```
-    编译后在`release`目录可以找到对应可执行文件。
-    ```sh
-    release/paopao
-    ```
-
-4. 直接运行后端    
-    运行api服务:
-    ```sh
-    make run
-    ```
-    运行api服务、web前端ui服务:
-    ```sh
-    make run TAGS='embed'
-    ```
-    提示: 如果需要内嵌web前端ui，请先构建web前端(建议设置web/.env为VITE_HOST="")。
-
-5. 使用内置的Migrate机制自动升级维护SQL DDL:
-    ```sh
-    # 添加 Migration 功能到 Features 中 开启migrate功能
-    vim config.yaml
-    # file: config.yaml
-    # Features:
-    #   Default: ["Base", "MySQL", "Zinc", "MinIO", "LoggerZinc", "Migration"]
-   
-    # 编译时加入migration tag编译出支持migrate功能的可执行文件
-    make build TAGS='migration'
-    release/paopao
-
-    # 或者 带上migration tag直接运行
-    make run TAGS='migration'
-    ```
-    > 注意：默认编译出来的可执行文件是不内置migrate功能，需要编译时带上migration tag才能内置支持migrage功能。
-
-
-#### 前端
-
-1. 进入前端目录 `web`，拷贝`.env` 到 `.env.local`，编辑 `.env.local ` 文件中后端服务地址及其他配置项，下载依赖包
-
-    ```sh
-    cd ./web && cp .env .env.local
-    vim .env.local
-    yarn
-    ```
-
-2. 编译前端
-
-    ```sh
-    yarn build
-    ```
-
-    build完成后，可以在dist目录获取编译产出，配置nginx指向至该目录即可
-
-#### 桌面端
-
-1. 进入前端目录 `web`，拷贝`.env` 到 `.env.local`，编辑 `.env.local ` 文件中后端服务地址及其他配置项，下载依赖包
-
-    ```sh
-    cd ./web && cp .env .env.local
-    vim .env.local
-    yarn
-    ```
-
-2. 编译前端
-
-    ```sh
-    yarn build
-    ```
-   
-3. 构建桌面端
-   ```sh
-   yarn tauri build
-   ```
-   桌面端是使用[Rust](https://www.rust-lang.org/) + [tauri](https://github.com/tauri-apps/tauri)编写
-   的，需要安装tauri的依赖，具体参考[https://tauri.studio/v1/guides/getting-started/prerequisites](https://tauri.studio/v1/guides/getting-started/prerequisites).
-
-
-### 方式二. 使用Docker构建、运行
-  * 后端:
-  ```sh
-  # 默认参数构建, 默认内嵌web ui并设置api host为空
-  docker build -t your/paopao-ce:tag .
-
-  # 内嵌web ui并且自定义API host参数
-  docker build -t your/paopao-ce:tag --build-arg API_HOST=http://api.paopao.info .
-
-  # 内嵌web ui并且使用本地web/.env中的API host
-  docker build -t your/paopao-ce:tag --build-arg USE_API_HOST=no .
-
-  # 内嵌web ui并且使用本地编译的web/dist构建
-  docker build -t your/paopao-ce:tag --build-arg USE_DIST=yes .
-
-  # 只编译api server
-  docker build -t your/paopao-ce:tag --build-arg EMBED_UI=no .
-
-  # 运行
-  mkdir custom && docker run -d -p 8008:8008 -v ${PWD}/custom:/app/paopao-ce/custom -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml your/paopao-ce:tag
-
-  # 或者直接运行构建好的docker image
-  mkdir custom && docker run -d -p 8008:8008 -v ${PWD}/custom:/app/paopao-ce/custom -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml bitbus/paopao-ce:latest
-  ```
+# Installation Guide
 
-  * 前端:
-  ```sh
-  cd web
+English | [简体中文](INSTALL_ZH.md)
 
-  # 默认参数构建
-  docker build -t your/paopao-ce:web .
+This guide covers the recommended ways to run PaoPao in development, evaluation, and self-hosted deployments. For a project overview, see [README.md](README.md).
 
-  # 自定义API host 参数构建
-  docker build -t your/paopao-ce:web --build-arg API_HOST=http://api.paopao.info .
+## Choose an Installation Path
 
-  # 使用本地编译的dist构建
-  docker build -t your/paopao-ce:web --build-arg USE_DIST=yes .
+| Scenario | Recommended path |
+| --- | --- |
+| Quick local evaluation | [Docker Compose](#docker-compose) |
+| Container-based deployment | [Docker images](#docker-images) |
+| Backend or frontend development | [Run from source](#run-from-source) |
+| Desktop client build | [Desktop app](#desktop-app) |
 
-  # 运行
-  docker run -d -p 8010:80 your/paopao-ce:web
-  ```
+## Requirements
 
-  * All-In-One:
-  ```sh
-  # 构建Image
-  docker buildx build --build-arg USE_DIST="yes" -t your/paopao-ce:all-in-one-latest -f Dockerfile.allinone .
+### For source-based development
 
-  # 运行
-  docker run --name paopao-ce-allinone  -d -p 8000:8008 -p 7700:7700 -v ./data/custom:/app/custom -v ./data/meili_data:/app/meili_data your/paopao-ce:all-in-one-latest
+- Go `1.24+`
+- Node.js `20.19+` or `22.12+`
+- Yarn `1.x`
+- MySQL `5.7+` if using the MySQL path
+- Redis
+- Meilisearch
+- Rust and the platform prerequisites required by Tauri if you want to build the desktop client
 
-  # 或者使用官方Image运行
-  docker run --name paopao-ce-allinone  -d -p 8000:8008 -p 7700:7700 -v ./data/custom:/app/custom -v ./data/meili_data:/app/meili_data bitbus/paopao-ce:all-in-one-latest
+### Helpful repository files
 
-  # 或者使用官方Image运行 + 自定义config.yaml
-  docker run --name paopao-ce-allinone  -d -p 8000:8008 -p 7700:7700 -v ./config.yaml:/app/config.yaml -v ./data/custom:/app/custom -v ./data/meili_data:/app/meili_data bitbus/paopao-ce:all-in-one-latest
-  ```
-  > 注意在`config.yaml` 中`Meili.ApiKey`的值必须与容器中meili启动时设定的`MEILI_MASTER_KEY`环境变量值相同，默认为`paopao-meilisearch`. 可以在docker启动容器时通过`-e MEILI_MASTER_KEY=<custom-key>`设置该值。
+- `config.yaml.sample` - canonical configuration template
+- `scripts/paopao-mysql.sql` - MySQL bootstrap schema
+- `scripts/paopao-postgres.sql` - PostgreSQL bootstrap schema
+- `scripts/paopao-sqlite3.sql` - SQLite bootstrap schema
+- `docker-compose.yaml` - local multi-service environment
 
+<a id="docker-compose"></a>
+
+## Option 1: Docker Compose (recommended for quick evaluation)
+
+This is the fastest way to start a local environment with the main dependencies wired together.
 
-### 方式三. 使用 docker-compose 运行
 ```sh
 git clone https://github.com/rocboss/paopao-ce.git
-cd paopao-ce && docker compose up -d
-# visit http://localhost:8008  👀 paopao-ce
-# visit http://localhost:8001  👀 RedisInsight
-# visit http://localhost:8080  👀 phpMyAdmin
+cd paopao-ce
+docker compose up -d
 ```
 
-默认是使用config.yaml.sample的配置，如果需要自定义配置，请拷贝默认配置文件(比如config.yaml)，修改后再同步配置到docker-compose.yaml如下：
+The default compose setup starts these services:
+
+- `http://localhost:8008` - PaoPao application
+- `http://localhost:7700` - Meilisearch
+- `http://localhost:8001` - RedisInsight
+- `http://localhost:3306` - MySQL
+
+Notes:
 
+- The backend container mounts `./config.yaml.sample` as its runtime config by default.
+- Persistent data is stored under `./custom/`.
+- Optional services such as MinIO, OpenObserve, Pyroscope, and phpMyAdmin are present in `docker-compose.yaml` but commented out by default.
+
+If you want to use a custom config file, replace the mounted file in `docker-compose.yaml`:
+
+```yaml
+backend:
+  volumes:
+    - ./config.yaml:/app/paopao-ce/config.yaml
+    - ./custom:/app/paopao-ce/custom
 ```
-# file: docker-compose.yaml
-...
-  backend:
-    image: bitbus/paopao-ce:latest
-    restart: always
-    depends_on:
-      - db
-      - redis
-      - zinc
-    # modify below to reflect your custom configure
-    volumes:
-      - ./config.yaml:/app/paopao-ce/config.yaml
-    ports:
-      - 8008:8008
-    networks:
-      - paopao-network
-....
+
+<a id="docker-images"></a>
+
+## Option 2: Docker Images
+
+### Backend image
+
+```sh
+# Default build: embeds the web UI and uses the default API host behavior
+docker build -t your/paopao-ce:tag .
+
+# Embed the web UI and set a custom API host
+docker build -t your/paopao-ce:tag --build-arg API_HOST=http://api.paopao.info .
+
+# Embed the web UI and keep the API host from local web/.env
+docker build -t your/paopao-ce:tag --build-arg USE_API_HOST=no .
+
+# Build with a precompiled local web/dist
+docker build -t your/paopao-ce:tag --build-arg USE_DIST=yes .
+
+# Build backend only, without embedded web UI
+docker build -t your/paopao-ce:tag --build-arg EMBED_UI=no .
 ```
 
-> 注意：默认提供的 docker-compose.yaml 初衷是搭建本机开发调试环境，如果需要产品部署供外网访问，请自行调优配置参数或使用其他方式部署。
+Run a locally built image:
 
-### 开发文档
-#### Docs文档说明
-`docs`目录提供了各种开发文档，包括：  
-* [deploy](docs/deploy/)     - paopao-ce部署文档
-* [discuss](docs/discuss/)   - 开发相关的问题交流论述文档
-* [openapi](docs/openapi/)   - paopao-ce后端导出API文档
-* [proposal](docs/proposal/) - paopao-ce功能特性提按文档
-> 比如，关于paopao-ce的设计定位，可以参考[docs/proposal/22110411-关于paopao-ce的设计定位](docs/proposal/22110411-关于paopao-ce的设计定位.md)，简要阐述了paopao-ce是如何定位自身的。
+```sh
+mkdir -p custom
+docker run -d -p 8008:8008 \
+  -v ${PWD}/custom:/app/paopao-ce/custom \
+  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
+  your/paopao-ce:tag
+```
 
-#### API文档
-开发者可以在本地开启`Docs`服务，浏览后端导出的API服务接口文档。  
-* `config.yaml` 添加 `Docs` 功能项:
-```yaml
-...
-Features:
-  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile", "Docs"]
-  Docs: ["Docs:OpenAPI"]
-...
+Or use the published image:
+
+```sh
+mkdir -p custom
+docker run -d -p 8008:8008 \
+  -v ${PWD}/custom:/app/paopao-ce/custom \
+  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
+  bitbus/paopao-ce:latest
 ```
 
-* 构建时将 `docs` 添加到TAGS中:
+### Web image
+
 ```sh
-make run TAGS='docs'
+cd web
 
-# visit http://127.0.0.1:8011/docs/openapi
+# Default build
+docker build -t your/paopao-ce:web .
+
+# Build with a custom API host
+docker build -t your/paopao-ce:web --build-arg API_HOST=http://api.paopao.info .
+
+# Build with a precompiled local dist
+docker build -t your/paopao-ce:web --build-arg USE_DIST=yes .
+
+# Run
+docker run -d -p 8010:80 your/paopao-ce:web
+```
+
+### All-in-one image
+
+```sh
+# Build
+docker buildx build --build-arg USE_DIST=yes -t your/paopao-ce:all-in-one-latest -f Dockerfile.allinone .
+
+# Run a local image
+docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
+  -v ./data/custom:/app/custom \
+  -v ./data/meili_data:/app/meili_data \
+  your/paopao-ce:all-in-one-latest
+
+# Run the published image
+docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
+  -v ./data/custom:/app/custom \
+  -v ./data/meili_data:/app/meili_data \
+  bitbus/paopao-ce:all-in-one-latest
 ```
 
-### 配置说明
+If you mount a custom `config.yaml`, make sure `Meili.ApiKey` matches the container's `MEILI_MASTER_KEY`. The default key is `paopao-meilisearch`.
 
-`config.yaml.sample` 是一份完整的配置文件模版，paopao-ce启动时会读取`./custom/config.yaml`、`./config.yaml`任意一份配置文件（优先读取最先找到的文件）。
+<a id="run-from-source"></a>
+
+## Option 3: Run from Source
+
+### Backend
+
+1. Initialize your database with the matching SQL file for your chosen database engine.
+2. Copy the configuration template.
+3. Adjust the storage, database, cache, and search settings for your environment.
+4. Run or build the backend.
 
 ```sh
 cp config.yaml.sample config.yaml
-vim config.yaml # 修改参数
-paopao serve
+make run
 ```
 
-配置文件中的 `Features` 小节是声明paopao-ce运行时开启哪些功能项:
+Build a release binary:
 
-```yaml
-...
-
-Features:
-  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile"]
-  Develop: ["Base", "MySQL", "Option", "Sms", "AliOSS", "LoggerOtlp"]
-  Demo: ["Base", "MySQL", "Option", "Sms", "MinIO", "LoggerOtlp"]
-  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile"]
-  Base: ["Zinc", "Redis", "Alipay",]
-  Option: ["SimpleCacheIndex"]
-  Sms: "SmsJuhe"
-
-...
+```sh
+make build
 ```
 
-如上： 
-Default/Develop/Demo/Slim 是不同 功能集套件(Features Suite)， Base/Option 是子功能套件， Sms是关于短信验证码功能的参数选项。
+The binary is written to `release/paopao`.
+
+### Web frontend
 
-这里 `Default`套件 代表的意思是： 使用`Base/Option` 中的功能，外加 `MySQL/LocalOSS/LoggerFile`功能，也就是说开启了`Zinc/Redis/Alipay/SimpleCacheIndex/MySQL/LocalOSS/LoggerFile` 7项功能； 
-`Develop`套件依例类推。 
+```sh
+cd web
+cp .env .env.local
+yarn
+yarn dev
+```
 
-使用Feautures:
+Build the web bundle:
 
 ```sh
-release/paopao serve --help
-Usage of release/paopao:
-  -features value
-        use special features
-  -no-default-features
-        whether use default features
-
-# 默认使用 Default 功能套件
-release/paopao serve
+yarn build
+```
 
-# 不包含 default 中的功能集，仅仅使用 develop 中声明的功能集
-release/paopao serve --no-default-features --features develop 
+### Embedded web UI
 
-# 使用 default 中的功能集，外加 sms 功能
-release/paopao serve --features sms  
+If you want the Go service to serve the web frontend directly, build the frontend assets first and then run with the `embed` tag:
 
-# 手动指定需要开启的功能集
-release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis 
+```sh
+make build-web
+make run TAGS='embed'
 ```
 
-目前支持的功能集合:
-| 功能项 | 类别 | 状态 | 备注 |
-| ----- | ----- | ----- | ----- |
-|`Web` | 子服务 | 内测 | 开启Web服务|
-|`Admin` | 子服务 | WIP | 开启Admin后台运维服务|
-|`SpaceX` | 子服务 | WIP | 开启SpaceX服务|
-|`Bot` | 子服务 | WIP | 开启Bot服务|
-|`NativeOBS` | 子服务 | WIP | 开启NativeOBS服务|
-|`Docs` | 子服务 | WIP | 开启开发者文档服务|
-|`Frontend:Web` | 子服务 | 稳定 | 开启独立前端服务|
-|`Frontend:EmbedWeb` | 子服务 | 稳定 | 开启内嵌于后端Web API服务中的前端服务|
-|`Gorm` | 数据库 | 稳定(默认) | 使用[gorm](https://github.com/go-gorm/gorm)作为数据库的ORM，默认使用 `Gorm` + `MySQL`组合|
-|`Sqlx`| 数据库 | WIP | 使用[sqlx](https://github.com/jmoiron/sqlx)作为数据库的ORM|
-|`Sqlc`| 数据库 | WIP | 使用[sqlc](https://github.com/kyleconroy/sqlc)自动生成ORM代码|
-|`MySQL`| 数据库 | 稳定(默认) | 使用MySQL作为数据库|
-|`Postgres`| 数据库 | 稳定 | 使用PostgreSQL作为数据库|
-|`Sqlite3`| 数据库 | 稳定 | 使用Sqlite3作为数据库|
-|`AliOSS` | 对象存储 | 稳定(推荐) |阿里云对象存储服务|
-|`COS` | 对象存储 | 内测 |腾讯云对象存储服务|
-|`HuaweiOBS` | 对象存储 | 内测 |华为云对象存储服务|
-|`MinIO` | 对象存储 | 稳定 |[MinIO](https://github.com/minio/minio)对象存储服务|
-|`S3` | 对象存储 | 内测 |AWS S3兼容的对象存储服务|
-|`LocalOSS` | 对象存储 | 内测 |提供使用本地目录文件作为对象存储的功能，仅用于开发调试环境|
-|`OSS:Retention` | 对象存储 | 内测 |基于对象存储系统的对象过期自动删除特性实现 先创建临时对象再持久化的功能|
-|`OSS:TempDir` | 对象存储 | 内测 |基于对象存储系统的对象拷贝/移动特性实现 先创建临时对象再持久化的功能|
-|`Redis` | 缓存 | 稳定 | Redis缓存功能 |
-|`SimpleCacheIndex` | 缓存 | Deprecated | 提供简单的 广场推文列表 的缓存功能 |
-|`BigCacheIndex` | 缓存 | Deprecated | 使用[BigCache](https://github.com/allegro/bigcache)缓存 广场推文列表，缓存每个用户每一页，简单做到千人千面 |
-|`RedisCacheIndex` | 缓存 | Deprecated | 使用Redis缓存 广场推文列表，缓存每个用户每一页，简单做到千人千面 |
-|`Zinc` | 搜索 | Deprecated | 基于[Zinc](https://github.com/zinclabs/zinc)搜索引擎提供推文搜索服务 |
-|`Meili` | 搜索 | 稳定(推荐) | 基于[Meilisearch](https://github.com/meilisearch/meilisearch)搜索引擎提供推文搜索服务 |
-|`Bleve` | 搜索 | WIP | 基于[Bleve](https://github.com/blevesearch/bleve)搜索引擎提供推文搜索服务 |
-|[`Sentry`](docs/proposal/23040412-关于使用sentry用于错误追踪与性能检测的设计.md) | 监控 | 内测 | 使用Sentry进行错误跟踪与性能监控 |
-|`LoggerFile` | 日志 | 稳定 | 使用文件写日志 |
-|`LoggerZinc` | 日志 | Deprecated | 使用[Zinc](https://github.com/zinclabs/zinc)写日志 |
-|`LoggerMeili` | 日志 | Deprecated | 使用[Meilisearch](https://github.com/meilisearch/meilisearch)写日志 |
-|`LoggerOpenObserve` | 日志 | Deprecated | 使用[OpenObserve](https://github.com/openobserve/openobserve)写日志 |
-|`LoggerOtlp` | 日志 | 内测 | 使用[OpenTelemetry](https://github.com/open-telemetry/opentelemetry-go)写日志 |
-|[`Friendship`](docs/proposal/22110410-关于Friendship功能项的设计.md) | 关系模式 | 内置 Builtin | 弱关系好友模式，类似微信朋友圈 |
-|[`Followship`](docs/proposal/22110409-关于Followship功能项的设计.md) | 关系模式 | 内置 Builtin | 关注者模式，类似Twitter的Follow模式 |
-|[`Lightship`](docs/proposal/22121409-关于Lightship功能项的设计.md) | 关系模式 | 弃用 Deprecated | 开放模式，所有推文都公开可见 |
-|`Alipay` | 支付 | 稳定 | 开启基于[支付宝开放平台](https://open.alipay.com/)的钱包功能 |
-|`Sms` | 短信验证 | 稳定 | 开启短信验证码功能，用于手机绑定验证手机是否注册者的；功能如果没有开启，手机绑定时任意短信验证码都可以绑定手机 |
-|`Docs:OpenAPI` | 开发文档 | 稳定 | 开启openapi文档功能，提供web api文档说明(visit http://127.0.0.1:8008/docs/openapi) |
-|[`Pyroscope`](docs/proposal/23021510-关于使用pyroscope用于性能调试的设计.md)| 性能优化 | 内测 | 开启Pyroscope功能用于性能调试 |   
-|[`Pprof`](docs/proposal/23062905-添加Pprof功能特性用于获取Profile.md)| 性能优化 | 内测 | 开启Pprof功能收集Profile信息 |  
-|`PhoneBind` | 其他 | 稳定 | 手机绑定功能 |   
-|`UseAuditHook` | 其他 | 内测 | 使用审核hook功能 |   
-|`DisableJobManager` | 其他 | 内测 | 禁止使用JobManager功能 |   
-|`Web:DisallowUserRegister` | 功能特性 | 稳定 | 不允许用户注册 |     
-
-> 功能项状态详情参考 [features-status](features-status.md).
-     
-### 搭建依赖环境
-#### [Zinc](https://github.com/zinclabs/zinc) 搜索引擎:
-* Zinc运行
+<a id="desktop-app"></a>
+
+### Desktop app
+
+The desktop client is built from `web/` using Tauri:
+
 ```sh
-# 创建用于存放zinc数据的目录
-mkdir -p data/zinc/data
+cd web
+cp .env .env.local
+yarn
+yarn build
+yarn tauri build
+```
+
+Before running the Tauri build, install the platform prerequisites from the official Tauri documentation for your OS.
+
+## Common Build Tags
 
-# 使用Docker运行zinc
-docker run -d --name zinc --user root -v ${PWD}/data/zinc/data:/data -p 4080:4080 -e ZINC_FIRST_ADMIN_USER=admin -e ZINC_FIRST_ADMIN_PASSWORD=admin -e DATA_PATH=/data public.ecr.aws/zinclabs/zinc:latest
+| Tag | Purpose |
+| --- | --- |
+| `embed` | Serve the built web frontend from the Go binary |
+| `migration` | Include migration support in the backend binary |
+| `docs` | Enable the developer docs / OpenAPI service |
 
-# 查看zinc运行状态
-docker ps
-CONTAINER ID   IMAGE                                COMMAND                  CREATED        STATUS        PORTS                    NAMES
-41465feea2ff   getmeili/meilisearch:v0.27.0         "tini -- /bin/sh -c …"   20 hours ago   Up 20 hours   0.0.0.0:7700->7700/tcp   paopao-ce-meili-1
-7daf982ca062   public.ecr.aws/prabhat/zinc:latest   "/go/bin/zinc"           3 weeks ago    Up 6 days     0.0.0.0:4080->4080/tcp   zinc
+Examples:
 
-# 使用docker compose运行
-docker compose up -d zinc
-# visit http://localhost:4080 打开自带的ui管理界面
+```sh
+make build TAGS='migration'
+make run TAGS='docs'
+make run TAGS='embed'
 ```
 
-* 修改Zinc配置
+## Configuration Basics
+
+At startup, PaoPao reads either:
+
+1. `./custom/config.yaml`
+2. `./config.yaml`
+
+The first file found is used.
+
+The `Features` section controls which capability bundles are enabled:
+
 ```yaml
-# features中加上 Zinc 和 LoggerZinc
 Features:
-  Default: ["Zinc", "LoggerZinc", "Base", "Sqlite3", "BigCacheIndex","MinIO"]
-...
-LoggerZinc: # 使用Zinc写日志
-  Host: 127.0.0.1:4080  # 这里的host就是paopao-ce能访问到的zinc主机
-  Index: paopao-log
-  User: admin
-  Password: admin
-  Secure: False         # 如果使用https访问zinc就设置为True
-...
-Zinc: # Zinc搜索配置
-  Host: 127.0.0.1:4080
-  Index: paopao-data
-  User: admin
-  Password: admin
-  Secure: False
+  Default: ["Web", "Frontend:EmbedWeb", "Meili", "LocalOSS", "MySQL", "BigCacheIndex", "LoggerFile"]
+  Develop: ["Base", "MySQL", "BigCacheIndex", "Meili", "Sms", "AliOSS", "LoggerMeili", "OSS:Retention"]
+  Demo: ["Base", "MySQL", "Option", "Zinc", "Sms", "MinIO", "LoggerZinc", "Migration"]
+  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile", "OSS:TempDir"]
 ```
 
-#### [Meilisearch](https://github.com/meilisearch/meilisearch) 搜索引擎:
-* Meili运行
+Useful commands:
+
 ```sh
-mkdir -p data/meili/data
+# Use the default suite
+release/paopao serve
+
+# Use only the develop suite
+release/paopao serve --no-default-features --features develop
 
-# 使用Docker运行
-docker run -d --name meili -v ${PWD}/data/meili/data:/meili_data -p 7700:7700 -e MEILI_MASTER_KEY=paopao-meilisearch getmeili/meilisearch:v0.29.0
-# visit http://localhost:7700 打开自带的搜索前端ui
+# Add one extra feature on top of default
+release/paopao serve --features sms
 
-# 使用docker compose运行，需要删除docker-compose.yaml中关于meili的注释
-docker compose up -d meili
+# Specify features explicitly
+release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis
+```
+
+For feature maturity and support status, see [features-status.md](features-status.md).
+
+## Optional Infrastructure Services
+
+The default modern stack is centered on **Meilisearch**, **Redis**, and either **LocalOSS**, **MinIO**, or a cloud object store. Optional integrations can be started separately when needed.
 
-# 查看meili运行状态
-docker compose ps
-NAME                   COMMAND                  SERVICE             STATUS              PORTS
-paopao-ce-meili-1      "tini -- /bin/sh -c …"   meili               running             0.0.0.0:7700->7700/tcp
+### Meilisearch (recommended search engine)
+
+```sh
+mkdir -p data/meili/data
+docker run -d --name meili \
+  -v ${PWD}/data/meili/data:/meili_data \
+  -p 7700:7700 \
+  -e MEILI_MASTER_KEY=paopao-meilisearch \
+  getmeili/meilisearch:v0.29.0
 ```
 
-* 修改Meili配置
+Matching config example:
+
 ```yaml
-# features中加上 Meili 和 LoggerMeili
-Features:
-  Default: ["Meili", "LoggerMeili", "Base", "Sqlite3", "BigCacheIndex","MinIO"]
-...
-LoggerMeili: # 使用Meili写日志
+Meili:
   Host: 127.0.0.1:7700
-  Index: paopao-log
-  ApiKey: paopao-meilisearch
-  Secure: False
-  MinWorker: 5               # 最小后台工作者, 设置范围[5, 100], 默认5
-  MaxLogBuffer: 100          # 最大log缓存条数, 设置范围[10, 10000], 默认100
-...
-Meili: # Meili搜索配置
-  Host: 127.0.0.1:7700      # 这里的host就是paopao-ce能访问到的meili主机
   Index: paopao-data
   ApiKey: paopao-meilisearch
-  Secure: False             # 如果使用https访问meili就设置为True
+  Secure: False
 ```
 
-#### [MinIO](https://github.com/minio/minio) 对象存储服务
-* MinIO运行
+### MinIO
+
 ```sh
 mkdir -p data/minio/data
-
-# 使用Docker运行
-docker run -d --name minio -v ${PWD}/data/minio/data:/data -p 9000:9000 -p 9001:9001 -e MINIO_ROOT_USER=minio-root-user -e  MINIO_ROOT_PASSWORD=minio-root-password -e MINIO_DEFAULT_BUCKETS=paopao:public bitnami/minio:latest
-
-# 使用docker compose运行， 需要删除docker-compose.yaml中关于minio的注释
-docker compose up -d minio
+docker run -d --name minio \
+  -v ${PWD}/data/minio/data:/data \
+  -p 9000:9000 -p 9001:9001 \
+  -e MINIO_ROOT_USER=minio-root-user \
+  -e MINIO_ROOT_PASSWORD=minio-root-password \
+  -e MINIO_DEFAULT_BUCKETS=paopao:public \
+  bitnami/minio:latest
 ```
 
-* 修改Minio配置
+Matching config example:
+
 ```yaml
-# features中加上 MinIO
-Features:
-  Default: ["MinIO", "Meili", "LoggerMeili", "Base", "Sqlite3", "BigCacheIndex"]
-...
-MinIO: # MinIO 存储配置
-  AccessKey: Q3AM3UQ867SPQQA43P2F      # AccessKey/SecretKey 需要登入minio管理界面手动创建，管理界面地址: http://127.0.0.1:9001
+MinIO:
+  AccessKey: Q3AM3UQ867SPQQA43P2F
   SecretKey: zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG
   Secure: False
-  Endpoint: 127.0.0.1:9000             # 根据部署的minio主机修改对应地址
-  Bucket: paopao                       # 如上，需要在管理界面创建bucket并赋予外部可读写权限
-  Domain: 127.0.0.1:9000               # minio外网访问的地址(如果想让外网访问，这里需要设置为外网可访问到的minio主机地址)
-...
+  Endpoint: 127.0.0.1:9000
+  Bucket: paopao
+  Domain: 127.0.0.1:9000
 ```
 
-#### [OpenObserve](https://github.com/openobserve/openobserve) 日志收集、指标度量、轨迹跟踪
-* OpenObserve运行
+### OpenObserve
+
 ```sh
-# 使用Docker运行
-mkdir data && docker run -v $PWD/data:/data -e ZO_DATA_DIR="/data" -p 5080:5080 \
-    -e ZO_ROOT_USER_EMAIL="root@paopao.info" -e ZO_ROOT_USER_PASSWORD="paopao-ce" \
-    public.ecr.aws/zinclabs/openobserve:latest
-
-# 使用docker compose运行， 需要删除docker-compose.yaml中关于openobserve的注释
-docker compose up -d openobserve
-# visit http://loclahost:5080
+mkdir -p data/openobserve
+docker run -v ${PWD}/data/openobserve:/data \
+  -e ZO_DATA_DIR=/data \
+  -p 5080:5080 \
+  -e ZO_ROOT_USER_EMAIL=root@paopao.info \
+  -e ZO_ROOT_USER_PASSWORD=paopao-ce \
+  public.ecr.aws/zinclabs/openobserve:latest
 ```
 
-* 修改LoggerOpenObserve配置
-```yaml
-# features中加上 LoggerOpenObserve
-Features:
-  Default: ["Meili", "LoggerOpenObserve", "Base", "Sqlite3", "BigCacheIndex"]
-...
-LoggerOpenObserve: # 使用OpenObserve写日志
-  Host: 127.0.0.1:5080
-  Organization: paopao-ce
-  Stream: default
-  User: root@paopao.info
-  Password: tiFEI8UeJWuYA7kN
-  Secure: False
-...
-```
+### Pyroscope
 
-#### [Pyroscope](https://github.com/pyroscope-io/pyroscope) 性能剖析
-* Pyroscope运行
 ```sh
-mkdir -p data/minio/data
-
-# 使用Docker运行
 docker run -it -p 4040:4040 pyroscope/pyroscope:latest server
-# 使用docker compose运行， 需要删除docker-compose.yaml中关于pyroscope的注释
-docker compose up -d pyroscope
-# visit http://loclahost:4040
 ```
 
-* 修改Pyroscope配置
+### Zinc (legacy / optional)
+
+Zinc still appears in the repository and feature definitions, but the current default stack is Meilisearch-based. Use it only if you intentionally want the legacy search path.
+
+## Enable API Documentation Locally
+
+Add the Docs feature suite and run with the `docs` build tag:
+
 ```yaml
-# features中加上 Pyroscope
 Features:
-  Default: ["Meili", "LoggerMeili", "Base", "Sqlite3", "BigCacheIndex", "Pyroscope"]
-...
-Pyroscope: # Pyroscope配置
-  AppName: "paopao-ce"
-  Endpoint: "http://localhost:4040"   # Pyroscope server address
-  AuthToken:                          # Pyroscope authentication token
-  Logger:  none                       # Pyroscope logger (standard | logrus | none)
-...
+  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile", "Docs"]
+  Docs: ["Docs:OpenAPI"]
 ```
 
-### 源代码分支管理 
-**主代码库`github.com/rocboss/paopao-ce`**      
-```bash
-git branch
-main
-beta
-alpha
-dev
-jc/alimy
-jc/orziz
-r/paopao-ce
-r/paopao-pro
-r/paopao-plus
-r/paopao-xtra
-r/paopao-mini
+```sh
+make run TAGS='docs'
 ```
-**分支说明**  
-| 名称 | 说明 | 备注|
-| ----- | ----- | ----- |       
-| [`main`](https://github.com/rocboss/paopao-ce) | 主分支 |分支`main`是主分支，也是paopao-ce的稳定版本发布分支，只有经过内部测试，没有重大bug出现的稳定代码才会推进到这个分支；该分支主要由`beta`分支代码演进而来，原则上**只接受bug修复PR**。`rc版本/稳定版本` 发布都应该在`main`主分支中进行。|
-| [`beta`](https://github.com/rocboss/paopao-ce/tree/beta) | 公测分支 |分支`beta`是公测分支，代码推进到`main`主分支的候选分支；该分支主要由`alpha`分支代码演进而来，**接受bug修复以及新功能优化的PR**，原则上不接受新功能PR。`beta版本` 发布都应该在`beta`公测分支下进行。|
-| [`alpha`](https://github.com/rocboss/paopao-ce/tree/alpha) | 内测分支 |分支`alpha`是内测分支，代码推进到`beta`分支的候选分支；该分支主要由`dev`分支代码演进而来，**接受bug修复以及新功能相关的PR**，接受新功能PR。分支代码演进到一个里程碑式的阶段后**冻结所有新功能**，合并代码到`beta`公测分支进行下一阶段的持续演进。`alpha版本` 发布都应该在`alpha`内测分支下进行。|   
-| [`dev`](https://github.com/rocboss/paopao-ce/tree/dev) | 开发分支 | 分支`dev`是开发分支，**不定期频繁更新**，接受 *新功能PR、代码优化PR、bug修复PR*；**新功能PR** 都应该首先提交给`dev`分支进行合并，bug修复/新功能开发/代码优化 **阶段性冻结** 后将代码演进合并到`alpha`分支。|   
-| `feature/*` | 子功能分支 |`feature/*`是新功能子分支，一般新功能子分支都是 *从`dev`开发分支fork出来的*；子功能分支 **只专注于该新功能** 代码的开发/优化，待开发接近内测阶段 *提交新功能PR给`dev`分支进行review/merge*，待新功能代码演进到`beta`分支后，原则上是可以删除该分支，但也可以保留到稳定版本发布。**该分支专注于新功能的开发，只接受新功能的bug修复/优化PR**。|
-| `jc/*` |维护者的开发分支|`jc/*`是代码库维护者的开发分支，一般包含一些局部优化或者bug修复代码，有时可以直接将代码merge到`dev/beta`分支，原则上不允许直接merge代码到`main`主分支。|
-| `x/*` |实验分支|`x/*`是技术实验分支，某些技术的引入需要经过具体的代码实现与真实场景的测评，考量评估后如果某项技术适合引入到paopao-ce，就fork出一个`feature/*`分支，作为新功能引入到paopao-ce。一般一些比较激进的技术，从`dev`分支fork出一个新的`x/*`分支，各种尝试、考量、评估后，或丢弃、或引入到paopao-ce。|   
-| `t/*` | 临时分支 |`t/*`是临时发版本分支，一般 `beta` 分支演进到正式版本发布前的最后某个beta版本（比如v0.2.0-beta)就从beta分支fork出一个 `t/*` 分支用于向 `main` 分支提交 PR 用于Review，待 PR Reviewed 合并到 `main` 分支后，可以删除这个临时创建的分支。这样设计主要是考虑到有时合并到 `main` 分支时，需要Review的时间可能会长一些，而dev分支的代码又急需推进到beta分支以发布下一个alpha版本用于内测，相当于为下一个测试版本发布腾地方。|  
-| `r/*` |发行版本分支|`r/*`是不同发行版本分支，不同发行版本各有不同的侧重点，可以根据需要选择适合的发行版本。|
-
-**发行版本分支说明**  
-| 名称 | 说明 | 维护者 | 备注 |
-| ----- | ----- | ----- | ----- |   
-|[`paopao-ce`](https://github.com/rocboss/paopao-ce/tree/dev)|paopao-ce 主发行版本|[ROC](https://github.com/rocboss 'ROC')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/dev/internal/dao/jinzhu) 使用[gorm](https://github.com/go-gorm/gorm)作为数据逻辑层的ORM框架，适配MySQL/PostgreSQL/Sqlite3数据库。| 
-|[`r/paopao-ce`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce)|paopao-ce 主分支预览版本|[ROC](https://github.com/rocboss 'ROC')<br/>[北野](https://github.com/alimy 'Michael Li')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/dev/internal/dao/jinzhu) 使用[gorm](https://github.com/go-gorm/gorm)作为数据逻辑层的ORM框架，适配MySQL/PostgreSQL/Sqlite3数据库。代码较`main`分支新，是主发行版本的前瞻预览版本。|
-|[`r/paopao-ce-plus`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-plus)|paopao-ce-plus 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-plus/internal/dao/sakila) 使用[sqlx](https://github.com/jmoiron/sqlx)作为数据逻辑层的ORM框架，专注于为MySQL/PostgreSQL/Sqlite3使用更优化的查询语句以提升数据检索效率。建议熟悉[sqlx](https://github.com/jmoiron/sqlx)的开发人员可以基于此版本来做 二次开发。|
-|[`r/paopao-ce-pro`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-pro)|paopao-ce-pro 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-pro/internal/dao/slonik) 使用[sqlc](https://github.com/kyleconroy/sqlc)作为sql语句生成器自动生成ORM代码，专门针对特定数据库MySQL/PostgreSQL进行查询优化，熟悉[sqlc](https://github.com/kyleconroy/sqlc)的开发人员可以基于此版本来做 二次开发。(另：分支目前只使用[pgx-v5](https://github.com/jackc/pgx)适配了PostgreSQL数据库，后续或许会适配MySQL/TiDB数据库。)|
-|[`r/paopao-ce-xtra`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-xtra)|paopao-ce-xtra 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 是r/paopao-ce、r/paopao-ce-plus、r/paopao-ce-pro的合集|
-|[`r/paopao-ce-mini`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-mini)|paopao-ce-mini 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支是paopao-ce最小可用版本，专注于个人部署、一键傻瓜式最简部署|
-
-**代码分支演进图**        
-![](docs/proposal/.assets/000-01.png)
-
-### 部署站点信息
-* [官方 paopao.info](https://www.paopao.info)  
-> 具体部署站点信息请查阅 [deployed-sites](./deployed-sites.md 'deployed sites'). 欢迎站长将已部署PaoPao实例的站点信息添加到 [deployed-sites](./deployed-sites.md 'deployed sites') 列表中。
-
-#### Collaborator's paopao account
-| 昵称 | [@GitHub](https://github.com 'github.com') | [@PaoPao](https://www.paopao.info 'paopao.info') |
-| ----- | ----- | ----- | 
-| ROC | [ROC](https://github.com/rocboss 'ROC')|[ROC](https://www.paopao.info/#/u?s=roc 'ROC @roc')|
-| [北野](https://alimy.me '糊涂小栈') | [Michael Li](https://github.com/alimy 'Michael Li') | [alimy](https://www.paopao.info/#/u?s=alimy '北野 @alimy')|
-| [orzi!](https://orzi.me 'orzi! - 做一个有想法的人') | [orzi!](https://github.com/orziz 'orzi!')| [orzi](https://www.paopao.info/#/u?s=orzi 'orzi @orzi') |
-
-### 其他说明
-
-建议后端服务使用 `supervisor` 守护进程，并通过 `nginx` 反向代理后，提供API给前端服务调用。
-
-短信通道使用的[聚合数据](https://www.juhe.cn/)，如果申请不下来，可以考虑替换其他服务商。
-
-代码结构比较简单，很方便扩展，开发文档请参阅[docs](docs '开发文档').
-
-<!-- MARKDOWN LINKS & IMAGES -->
-[contributors-shield]: https://img.shields.io/github/contributors/rocboss/paopao-ce?style=flat
-[contributors-url]: https://github.com/rocboss/paopao-ce/graphs/contributors
-[goreport-shield]: https://goreportcard.com/badge/github.com/rocboss/paopao-ce
-[goreport-url]: https://goreportcard.com/report/github.com/rocboss/paopao-ce
-[forks-shield]: https://img.shields.io/github/forks/rocboss/paopao-ce?style=flat
-[forks-url]: https://github.com/rocboss/paopao-ce/network/members
-[stars-shield]: https://img.shields.io/github/stars/rocboss/paopao-ce.svg?style=flat
-[stars-url]: https://github.com/rocboss/paopao-ce/stargazers
-[issues-shield]: https://img.shields.io/github/issues/rocboss/paopao-ce.svg?style=flat
-[issues-url]: https://github.com/rocboss/paopao-ce/issues
-[license-shield]: https://img.shields.io/github/license/rocboss/paopao-ce.svg?style=flat
-[license-url]: https://github.com/rocboss/paopao-ce/blob/master/LICENSE.txt
-[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat&logo=linkedin&colorB=555
-[product-light-screenshot]: https://assets.paopao.info/static/paopao-light.jpeg
-[product-dark-screenshot]: https://assets.paopao.info/static/paopao-dark.jpeg
+
+Then visit:
+
+- `http://127.0.0.1:8011/docs/openapi`
+
+## Additional Deployment Docs
+
+For platform-specific or production-oriented deployment references, see:
+
+- [docs/deploy/README.md](docs/deploy/README.md)
+- [docs/deploy/core/](docs/deploy/core/)
+- [docs/deploy/local/](docs/deploy/local/)
+- [docs/deploy/k8s/](docs/deploy/k8s/)
+- [docs/deploy/aliyun/](docs/deploy/aliyun/)
+- [docs/deploy/huawei/](docs/deploy/huawei/)
+- [docs/deploy/tencent/](docs/deploy/tencent/)
+
+## Operational Notes
+
+- For long-running deployments, it is reasonable to run the backend under a process manager and place Nginx in front of the application.
+- The SMS implementation currently references Juhe in the sample configuration. If that provider is not suitable for your deployment, replace it with another compatible service.
+- The repository includes multiple runtime combinations; keep your selected `Features` set aligned with the infrastructure you actually provision.
diff --git a/INSTALL_ZH.md b/INSTALL_ZH.md
new file mode 100644
index 00000000..504c7c78
--- /dev/null
+++ b/INSTALL_ZH.md
@@ -0,0 +1,375 @@
+# 安装指南
+
+[English](INSTALL.md) | 简体中文
+
+本文档介绍 PaoPao 在本地体验、开发调试和自部署场景下的推荐安装方式。项目整体说明请参考 [README_ZH.md](README_ZH.md)。
+
+## 选择安装方式
+
+| 场景 | 推荐方式 |
+| --- | --- |
+| 快速本地体验 | [Docker Compose](#docker-compose) |
+| 基于容器部署 | [Docker 镜像](#docker-images) |
+| 后端或前端开发 | [源码运行](#run-from-source) |
+| 构建桌面端 | [桌面应用](#desktop-app) |
+
+## 环境要求
+
+### 源码开发所需环境
+
+- Go `1.24+`
+- Node.js `20.19+` 或 `22.12+`
+- Yarn `1.x`
+- 若使用 MySQL 方案，需要 MySQL `5.7+`
+- Redis
+- Meilisearch
+- 如果需要构建桌面端，还需要安装 Rust 以及 Tauri 对应平台依赖
+
+### 关键文件
+
+- `config.yaml.sample` - 标准配置模板
+- `scripts/paopao-mysql.sql` - MySQL 初始化脚本
+- `scripts/paopao-postgres.sql` - PostgreSQL 初始化脚本
+- `scripts/paopao-sqlite3.sql` - SQLite 初始化脚本
+- `docker-compose.yaml` - 本地多服务启动配置
+
+<a id="docker-compose"></a>
+
+## 方案 1：Docker Compose（推荐用于快速体验）
+
+这是最快速的本地启动方式，适合先把主流程跑起来。
+
+```sh
+git clone https://github.com/rocboss/paopao-ce.git
+cd paopao-ce
+docker compose up -d
+```
+
+默认会启动以下服务：
+
+- `http://localhost:8008` - PaoPao 应用
+- `http://localhost:7700` - Meilisearch
+- `http://localhost:8001` - RedisInsight
+- `http://localhost:3306` - MySQL
+
+说明：
+
+- 后端容器默认会将 `./config.yaml.sample` 挂载为运行配置。
+- 持久化数据默认保存在 `./custom/` 目录下。
+- `docker-compose.yaml` 中还预留了 MinIO、OpenObserve、Pyroscope、phpMyAdmin 等可选服务，但默认是注释状态。
+
+如果需要使用自定义配置文件，可将 `docker-compose.yaml` 中的挂载改为：
+
+```yaml
+backend:
+  volumes:
+    - ./config.yaml:/app/paopao-ce/config.yaml
+    - ./custom:/app/paopao-ce/custom
+```
+
+<a id="docker-images"></a>
+
+## 方案 2：Docker 镜像
+
+### 后端镜像
+
+```sh
+# 默认构建：内嵌 Web UI，并使用默认 API host 逻辑
+docker build -t your/paopao-ce:tag .
+
+# 内嵌 Web UI，并指定 API host
+docker build -t your/paopao-ce:tag --build-arg API_HOST=http://api.paopao.info .
+
+# 内嵌 Web UI，并沿用本地 web/.env 中的 API host
+docker build -t your/paopao-ce:tag --build-arg USE_API_HOST=no .
+
+# 使用本地预编译的 web/dist 构建
+docker build -t your/paopao-ce:tag --build-arg USE_DIST=yes .
+
+# 仅构建后端，不内嵌 Web UI
+docker build -t your/paopao-ce:tag --build-arg EMBED_UI=no .
+```
+
+运行本地构建镜像：
+
+```sh
+mkdir -p custom
+docker run -d -p 8008:8008 \
+  -v ${PWD}/custom:/app/paopao-ce/custom \
+  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
+  your/paopao-ce:tag
+```
+
+或者直接使用已发布镜像：
+
+```sh
+mkdir -p custom
+docker run -d -p 8008:8008 \
+  -v ${PWD}/custom:/app/paopao-ce/custom \
+  -v ${PWD}/config.yaml.sample:/app/paopao-ce/config.yaml \
+  bitbus/paopao-ce:latest
+```
+
+### Web 镜像
+
+```sh
+cd web
+
+# 默认构建
+docker build -t your/paopao-ce:web .
+
+# 自定义 API host
+docker build -t your/paopao-ce:web --build-arg API_HOST=http://api.paopao.info .
+
+# 使用本地预编译 dist 构建
+docker build -t your/paopao-ce:web --build-arg USE_DIST=yes .
+
+# 运行
+docker run -d -p 8010:80 your/paopao-ce:web
+```
+
+### All-in-one 镜像
+
+```sh
+# 构建
+docker buildx build --build-arg USE_DIST=yes -t your/paopao-ce:all-in-one-latest -f Dockerfile.allinone .
+
+# 运行本地镜像
+docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
+  -v ./data/custom:/app/custom \
+  -v ./data/meili_data:/app/meili_data \
+  your/paopao-ce:all-in-one-latest
+
+# 运行已发布镜像
+docker run --name paopao-ce-allinone -d -p 8000:8008 -p 7700:7700 \
+  -v ./data/custom:/app/custom \
+  -v ./data/meili_data:/app/meili_data \
+  bitbus/paopao-ce:all-in-one-latest
+```
+
+如果挂载了自定义 `config.yaml`，请确保其中的 `Meili.ApiKey` 与容器内的 `MEILI_MASTER_KEY` 保持一致。默认值为 `paopao-meilisearch`。
+
+<a id="run-from-source"></a>
+
+## 方案 3：从源码运行
+
+### 后端
+
+1. 按照所选数据库导入对应 SQL 初始化脚本。
+2. 复制配置模板。
+3. 根据本地环境调整存储、数据库、缓存和搜索相关配置。
+4. 启动或构建后端。
+
+```sh
+cp config.yaml.sample config.yaml
+make run
+```
+
+构建发布二进制：
+
+```sh
+make build
+```
+
+生成的二进制默认位于 `release/paopao`。
+
+### Web 前端
+
+```sh
+cd web
+cp .env .env.local
+yarn
+yarn dev
+```
+
+构建 Web 静态资源：
+
+```sh
+yarn build
+```
+
+### 内嵌 Web UI
+
+如果希望由 Go 服务直接提供 Web 前端，请先构建前端资源，再使用 `embed` 标签运行：
+
+```sh
+make build-web
+make run TAGS='embed'
+```
+
+<a id="desktop-app"></a>
+
+### 桌面应用
+
+桌面端位于 `web/` 目录，使用 Tauri 构建：
+
+```sh
+cd web
+cp .env .env.local
+yarn
+yarn build
+yarn tauri build
+```
+
+执行 Tauri 构建前，请先安装对应操作系统的官方前置依赖。
+
+## 常用构建标签
+
+| 标签 | 作用 |
+| --- | --- |
+| `embed` | 将 Web 前端打包进 Go 二进制，由后端直接提供服务 |
+| `migration` | 在后端二进制中包含 migration 支持 |
+| `docs` | 启用开发文档 / OpenAPI 服务 |
+
+示例：
+
+```sh
+make build TAGS='migration'
+make run TAGS='docs'
+make run TAGS='embed'
+```
+
+## 配置基础
+
+启动时，PaoPao 会按以下顺序读取配置：
+
+1. `./custom/config.yaml`
+2. `./config.yaml`
+
+先找到哪个文件，就使用哪个文件。
+
+`Features` 用于控制不同能力组合：
+
+```yaml
+Features:
+  Default: ["Web", "Frontend:EmbedWeb", "Meili", "LocalOSS", "MySQL", "BigCacheIndex", "LoggerFile"]
+  Develop: ["Base", "MySQL", "BigCacheIndex", "Meili", "Sms", "AliOSS", "LoggerMeili", "OSS:Retention"]
+  Demo: ["Base", "MySQL", "Option", "Zinc", "Sms", "MinIO", "LoggerZinc", "Migration"]
+  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile", "OSS:TempDir"]
+```
+
+常见命令：
+
+```sh
+# 使用默认套件
+release/paopao serve
+
+# 仅使用 develop 套件
+release/paopao serve --no-default-features --features develop
+
+# 在默认套件基础上增加一个功能
+release/paopao serve --features sms
+
+# 手动显式指定功能项
+release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis
+```
+
+功能项成熟度与支持状态请参考 [features-status.md](features-status.md)。
+
+## 可选基础设施服务
+
+当前更推荐的默认组合是 **Meilisearch**、**Redis**，以及 **LocalOSS / MinIO / 云对象存储** 三选一。其他集成按需启用即可。
+
+### Meilisearch（推荐搜索引擎）
+
+```sh
+mkdir -p data/meili/data
+docker run -d --name meili \
+  -v ${PWD}/data/meili/data:/meili_data \
+  -p 7700:7700 \
+  -e MEILI_MASTER_KEY=paopao-meilisearch \
+  getmeili/meilisearch:v0.29.0
+```
+
+对应配置示例：
+
+```yaml
+Meili:
+  Host: 127.0.0.1:7700
+  Index: paopao-data
+  ApiKey: paopao-meilisearch
+  Secure: False
+```
+
+### MinIO
+
+```sh
+mkdir -p data/minio/data
+docker run -d --name minio \
+  -v ${PWD}/data/minio/data:/data \
+  -p 9000:9000 -p 9001:9001 \
+  -e MINIO_ROOT_USER=minio-root-user \
+  -e MINIO_ROOT_PASSWORD=minio-root-password \
+  -e MINIO_DEFAULT_BUCKETS=paopao:public \
+  bitnami/minio:latest
+```
+
+对应配置示例：
+
+```yaml
+MinIO:
+  AccessKey: Q3AM3UQ867SPQQA43P2F
+  SecretKey: zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG
+  Secure: False
+  Endpoint: 127.0.0.1:9000
+  Bucket: paopao
+  Domain: 127.0.0.1:9000
+```
+
+### OpenObserve
+
+```sh
+mkdir -p data/openobserve
+docker run -v ${PWD}/data/openobserve:/data \
+  -e ZO_DATA_DIR=/data \
+  -p 5080:5080 \
+  -e ZO_ROOT_USER_EMAIL=root@paopao.info \
+  -e ZO_ROOT_USER_PASSWORD=paopao-ce \
+  public.ecr.aws/zinclabs/openobserve:latest
+```
+
+### Pyroscope
+
+```sh
+docker run -it -p 4040:4040 pyroscope/pyroscope:latest server
+```
+
+### Zinc（遗留 / 可选）
+
+仓库中仍保留了 Zinc 相关代码与 Feature 定义，但当前默认推荐的搜索方案是 Meilisearch。只有在你明确需要兼容旧方案时，再考虑启用 Zinc。
+
+## 本地启用 API 文档
+
+在配置中加入 Docs 套件，并使用 `docs` 标签运行：
+
+```yaml
+Features:
+  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile", "Docs"]
+  Docs: ["Docs:OpenAPI"]
+```
+
+```sh
+make run TAGS='docs'
+```
+
+然后访问：
+
+- `http://127.0.0.1:8011/docs/openapi`
+
+## 更多部署文档
+
+如果需要平台化或生产化部署参考，请继续阅读：
+
+- [docs/deploy/README.md](docs/deploy/README.md)
+- [docs/deploy/core/](docs/deploy/core/)
+- [docs/deploy/local/](docs/deploy/local/)
+- [docs/deploy/k8s/](docs/deploy/k8s/)
+- [docs/deploy/aliyun/](docs/deploy/aliyun/)
+- [docs/deploy/huawei/](docs/deploy/huawei/)
+- [docs/deploy/tencent/](docs/deploy/tencent/)
+
+## 运维建议
+
+- 对于长期运行环境，建议使用进程守护工具管理后端服务，并通过 Nginx 做反向代理。
+- 示例配置中的短信通道使用 Juhe；如果不适合你的部署场景，可以替换为其他兼容服务商。
+- 项目支持多种运行组合，请确保 `Features` 与你实际部署的基础设施保持一致。
diff --git a/README.md b/README.md
index 266b7d22..c14cd89c 100644
--- a/README.md
+++ b/README.md
@@ -1,268 +1,243 @@
 <div id="top"></div>
 
-<!-- PROJECT SHIELDS -->
 [![Go](https://github.com/rocboss/paopao-ce/actions/workflows/go.yml/badge.svg)](https://github.com/rocboss/paopao-ce/actions/workflows/go.yml)
-[![Go Report Card][goreport-shield]][goreport-url]
-[![Forks][forks-shield]][forks-url]
-[![Stargazers][stars-shield]][stars-url]
-[![MIT License][license-shield]][license-url]
-[![Contributors][contributors-shield]][contributors-url]
+[![Go Report Card](https://goreportcard.com/badge/github.com/rocboss/paopao-ce)](https://goreportcard.com/report/github.com/rocboss/paopao-ce)
+[![Forks](https://img.shields.io/github/forks/rocboss/paopao-ce?style=flat)](https://github.com/rocboss/paopao-ce/network/members)
+[![Stars](https://img.shields.io/github/stars/rocboss/paopao-ce.svg?style=flat)](https://github.com/rocboss/paopao-ce/stargazers)
+[![MIT License](https://img.shields.io/github/license/rocboss/paopao-ce.svg?style=flat)](https://github.com/rocboss/paopao-ce/blob/main/LICENSE)
+[![Contributors](https://img.shields.io/github/contributors/rocboss/paopao-ce?style=flat)](https://github.com/rocboss/paopao-ce/graphs/contributors)
 [![Sourcegraph](https://img.shields.io/badge/view%20on-Sourcegraph-brightgreen.svg)](https://sourcegraph.com/github.com/rocboss/paopao-ce)
 
-<!-- PROJECT LOGO -->
 <div align="center">
   <a href="https://github.com/rocboss/paopao-ce">
-    <img src="https://assets.paopao.info/static/paopao-logo.png" alt="Logo" width="80" height="80">
+    <img src="https://assets.paopao.info/static/paopao-logo.png" alt="PaoPao logo" width="88" height="88">
   </a>
 
-  <h3 align="center">PaoPao</h3>
+  <h1 align="center">PaoPao</h1>
 
   <p align="center">
-    🔥一个清新文艺的微社区
+    An open-source micro-community platform built with Go and Vue.
     <br />
-    <a href="https://www.paopao.info/">View Demo</a>
+    Designed for self-hosted social products, community experiments, and customizable deployments.
+  </p>
+
+  <p align="center">
+    <a href="README_ZH.md">简体中文</a>
+    ·
+    <a href="https://www.paopao.info/">Live Demo</a>
     ·
-    <a href="https://github.com/rocboss/paopao-ce/pulls">Pull Request</a>
+    <a href="https://github.com/rocboss/paopao-ce/pulls">Pull Requests</a>
     ·
-    <a href="https://www.yuque.com/rocs/paopao/about">Features</a>
+    <a href="https://www.yuque.com/rocs/paopao/about">Project Notes</a>
   </p>
 </div>
 
 ---
 
-## 预览
-Web端：  
-[![明色主题][product-light-screenshot]](https://www.paopao.info)
+## Overview
+
+PaoPao is a full-stack, open-source micro-community system. It combines a Go backend, a Vue 3 web client, and an optional Tauri desktop application, with a modular feature system for storage, search, logging, observability, and deployment strategy.
+
+The repository is suitable for teams or individuals who want to run a community product, evaluate an extensible social platform, or build on top of an existing codebase instead of starting from scratch.
+
+## Why PaoPao
+
+- **Full-stack delivery**: backend, web frontend, and desktop packaging live in one repository.
+- **Modular runtime features**: enable different capability sets through `Features` suites such as `Default`, `Develop`, `Demo`, and `Slim`.
+- **Flexible infrastructure**: supports MySQL, PostgreSQL, SQLite, Redis, Meilisearch, and multiple object storage providers.
+- **Multiple deployment paths**: run from source, Docker, Docker Compose, or all-in-one container images.
+- **Self-hosting friendly**: configuration is file-based and operational docs are already included in the repo.
 
-[![暗色主题][product-dark-screenshot]](https://www.paopao.info)
+## Preview
 
-更多演示请前往[官网](https://www.paopao.info)体验（谢绝灌水）  
+### Web
+
+[![Light theme preview](https://assets.paopao.info/static/paopao-light.jpeg)](https://www.paopao.info)
+
+[![Dark theme preview](https://assets.paopao.info/static/paopao-dark.jpeg)](https://www.paopao.info)
+
+### Desktop
 
-桌面端：  
 ![](docs/proposal/.assets/000-00.jpg)
 
-<p align="right">(<a href="#top">back to top</a>)</p>
+More screenshots and live behavior are available at [paopao.info](https://www.paopao.info/).
 
-## 🛠 技术栈
+## Architecture at a Glance
 
-PaoPao主要由以下优秀的开源项目/工具构建  
-#### 后端:
-* [Go](https://go.dev/ 'go')
-* [Gin](https://gin-gonic.com/ 'gin')
-* [Mir](https://github.com/alimy/mir 'go-mir')
-* [Meilisearch](https://www.meilisearch.com/ 'meilisearch')
-* [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-go 'OpenTelemetry')
-* [OpenObserve](https://github.com/openobserve/openobserve 'OpenObserve')
+| Layer | Primary stack |
+| --- | --- |
+| Backend | Go, Gin, Cobra, GORM, Mir |
+| Web frontend | Vue 3, Vite, Naive UI |
+| Desktop client | Tauri |
+| Search | Meilisearch |
+| Cache | Redis |
+| Object storage | Local OSS, MinIO, AliOSS, COS, Huawei OBS, S3-compatible |
+| Observability | OpenTelemetry, Sentry, Pyroscope, Pprof |
 
-#### 前端: 
-* [Naive UI](https://www.naiveui.com/)
-* [Vue.js](https://vuejs.org/)
-* [Vite.js](https://vitejs.dev/)
-* [tauri](https://github.com/tauri-apps/tauri 'tauri')
+## Repository Layout
 
-<!-- GETTING STARTED -->
-## 🏗 快速开始
+| Path | Purpose |
+| --- | --- |
+| `cmd/`, `internal/`, `pkg/` | Backend application and shared packages |
+| `web/` | Vue 3 web application and Tauri desktop frontend |
+| `docs/` | Deployment, OpenAPI, design proposals, and related documentation |
+| `scripts/` | SQL bootstrap and helper assets |
+| `config.yaml.sample` | Complete runtime configuration template |
 
-### 环境要求
+## Quick Start
 
-* Go (1.22+)
-* Node.js (20.19+/22.12+)
-* MySQL (5.7+)
-* Redis
-* Meilisearch
+### Option A: Evaluate locally with Docker Compose
 
-以上环境版本为PaoPao官方的开发版本，仅供参考，其他版本的环境未进行充分测试
+This is the fastest way to bring up a local environment for evaluation.
+
+```sh
+git clone https://github.com/rocboss/paopao-ce.git
+cd paopao-ce
+docker compose up -d
+```
 
-### 安装说明
-参考  [安装说明 (INSTALL.md);](INSTALL.md '参考 安装说明')
+Then open:
 
-### 开发文档
-#### Docs文档说明
-`docs`目录提供了各种开发文档，包括：  
-* [deploy](docs/deploy/)     - paopao-ce部署文档
-* [openapi](docs/openapi/)   - paopao-ce后端导出API文档
-* [proposal](docs/proposal/) - paopao-ce功能特性提按文档
-> 比如，关于paopao-ce的设计定位，可以参考[docs/proposal/22110411-关于paopao-ce的设计定位](docs/proposal/22110411-关于paopao-ce的设计定位.md)，简要阐述了paopao-ce是如何定位自身的。
+- `http://localhost:8008` - PaoPao
+- `http://localhost:7700` - Meilisearch
+- `http://localhost:8001` - RedisInsight
 
-### 配置说明
+### Option B: Develop from source
 
-`config.yaml.sample` 是一份完整的配置文件模版，paopao-ce启动时会读取`./custom/config.yaml`、`./config.yaml`任意一份配置文件（优先读取最先找到的文件）。
+#### Requirements
+
+- Go `1.24+`
+- Node.js `20.19+` or `22.12+`
+- MySQL `5.7+`
+- Redis
+- Meilisearch
+- Rust + Tauri prerequisites if you plan to build the desktop app
+
+#### Backend
+
+1. Import `scripts/paopao-mysql.sql` into MySQL.
+2. Copy the sample config and adjust it for your environment.
+3. Start the backend.
 
 ```sh
 cp config.yaml.sample config.yaml
-vim config.yaml # 修改参数
-paopao serve
+make run
 ```
 
-配置文件中的 `Features` 小节是声明paopao-ce运行时开启哪些功能项:
+To build a release binary instead:
 
-```yaml
-...
+```sh
+make build
+```
+
+To serve the embedded web UI from the Go binary, build the web assets first and run with the `embed` tag:
+
+```sh
+make build-web
+make run TAGS='embed'
+```
+
+#### Web frontend
+
+```sh
+cd web
+cp .env .env.local
+yarn
+yarn dev
+```
 
+To produce static assets:
+
+```sh
+yarn build
+```
+
+#### Desktop app
+
+```sh
+cd web
+yarn tauri build
+```
+
+For the full installation guide, Docker build variants, desktop prerequisites, and migration notes, see [INSTALL.md](INSTALL.md).
+
+## Configuration and Feature Suites
+
+`config.yaml.sample` is the canonical configuration template. At runtime, PaoPao reads either `./custom/config.yaml` or `./config.yaml`, preferring the first file it finds.
+
+The `Features` section controls which capability bundles are enabled:
+
+```yaml
 Features:
   Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile"]
   Develop: ["Base", "MySQL", "Option", "Sms", "AliOSS", "LoggerOtlp"]
   Demo: ["Base", "MySQL", "Option", "Sms", "MinIO", "LoggerOtlp"]
   Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile"]
-  Base: ["Zinc", "Redis", "Alipay",]
+  Base: ["Zinc", "Redis", "Alipay"]
   Option: ["SimpleCacheIndex"]
   Sms: "SmsJuhe"
-
-...
 ```
 
-如上： 
-Default/Develop/Demo/Slim 是不同 功能集套件(Features Suite)， Base/Option 是子功能套件， Sms是关于短信验证码功能的参数选项。
-
-这里 `Default`套件 代表的意思是： 使用`Base/Option` 中的功能，外加 `MySQL/LocalOSS/LoggerFile`功能，也就是说开启了`Zinc/Redis/Alipay/SimpleCacheIndex/MySQL/LocalOSS/LoggerFile` 7项功能； 
-`Develop`套件依例类推。 
-
-使用Feautures:
+Typical examples:
 
 ```sh
-release/paopao serve --help
-Usage of release/paopao:
-  -features value
-        use special features
-  -no-default-features
-        whether use default features
-
-# 默认使用 Default 功能套件
+# Use the default suite
 release/paopao serve
 
-# 不包含 default 中的功能集，仅仅使用 develop 中声明的功能集
-release/paopao serve --no-default-features --features develop 
+# Use only the declared develop suite
+release/paopao serve --no-default-features --features develop
 
-# 使用 default 中的功能集，外加 sms 功能
-release/paopao serve --features sms  
+# Add sms on top of the default suite
+release/paopao serve --features sms
 
-# 手动指定需要开启的功能集
-release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis 
+# Enable features explicitly
+release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis
 ```
 
-目前支持的功能集合:
-| 功能项 | 类别 | 状态 | 备注 |
-| ----- | ----- | ----- | ----- |
-|`Web` | 子服务 | 内测 | 开启Web服务|
-|`Admin` | 子服务 | WIP | 开启Admin后台运维服务|
-|`SpaceX` | 子服务 | WIP | 开启SpaceX服务|
-|`Bot` | 子服务 | WIP | 开启Bot服务|
-|`NativeOBS` | 子服务 | WIP | 开启NativeOBS服务|
-|`Docs` | 子服务 | WIP | 开启开发者文档服务|
-|`Frontend:Web` | 子服务 | 稳定 | 开启独立前端服务|
-|`Frontend:EmbedWeb` | 子服务 | 稳定 | 开启内嵌于后端Web API服务中的前端服务|
-|`Gorm` | 数据库 | 稳定(默认) | 使用[gorm](https://github.com/go-gorm/gorm)作为数据库的ORM，默认使用 `Gorm` + `MySQL`组合|
-|`Sqlx`| 数据库 | WIP | 使用[sqlx](https://github.com/jmoiron/sqlx)作为数据库的ORM|
-|`Sqlc`| 数据库 | WIP | 使用[sqlc](https://github.com/kyleconroy/sqlc)自动生成ORM代码|
-|`MySQL`| 数据库 | 稳定(默认) | 使用MySQL作为数据库|
-|`Postgres`| 数据库 | 稳定 | 使用PostgreSQL作为数据库|
-|`Sqlite3`| 数据库 | 稳定 | 使用Sqlite3作为数据库|
-|`AliOSS` | 对象存储 | 稳定(推荐) |阿里云对象存储服务|
-|`COS` | 对象存储 | 内测 |腾讯云对象存储服务|
-|`HuaweiOBS` | 对象存储 | 内测 |华为云对象存储服务|
-|`MinIO` | 对象存储 | 稳定 |[MinIO](https://github.com/minio/minio)对象存储服务|
-|`S3` | 对象存储 | 内测 |AWS S3兼容的对象存储服务|
-|`LocalOSS` | 对象存储 | 内测 |提供使用本地目录文件作为对象存储的功能，仅用于开发调试环境|
-|`OSS:Retention` | 对象存储 | 内测 |基于对象存储系统的对象过期自动删除特性实现 先创建临时对象再持久化的功能|
-|`OSS:TempDir` | 对象存储 | 内测 |基于对象存储系统的对象拷贝/移动特性实现 先创建临时对象再持久化的功能|
-|`Redis` | 缓存 | 稳定 | Redis缓存功能 |
-|`SimpleCacheIndex` | 缓存 | Deprecated | 提供简单的 广场推文列表 的缓存功能 |
-|`BigCacheIndex` | 缓存 | Deprecated | 使用[BigCache](https://github.com/allegro/bigcache)缓存 广场推文列表，缓存每个用户每一页，简单做到千人千面 |
-|`RedisCacheIndex` | 缓存 | Deprecated | 使用Redis缓存 广场推文列表，缓存每个用户每一页，简单做到千人千面 |
-|`Zinc` | 搜索 | Deprecated | 基于[Zinc](https://github.com/zinclabs/zinc)搜索引擎提供推文搜索服务 |
-|`Meili` | 搜索 | 稳定(推荐) | 基于[Meilisearch](https://github.com/meilisearch/meilisearch)搜索引擎提供推文搜索服务 |
-|`Bleve` | 搜索 | WIP | 基于[Bleve](https://github.com/blevesearch/bleve)搜索引擎提供推文搜索服务 |
-|[`Sentry`](docs/proposal/23040412-关于使用sentry用于错误追踪与性能检测的设计.md) | 监控 | 内测 | 使用Sentry进行错误跟踪与性能监控 |
-|`LoggerFile` | 日志 | 稳定 | 使用文件写日志 |
-|`LoggerZinc` | 日志 | Deprecated | 使用[Zinc](https://github.com/zinclabs/zinc)写日志 |
-|`LoggerMeili` | 日志 | Deprecated | 使用[Meilisearch](https://github.com/meilisearch/meilisearch)写日志 |
-|`LoggerOpenObserve` | 日志 | Deprecated | 使用[OpenObserve](https://github.com/openobserve/openobserve)写日志 |
-|`LoggerOtlp` | 日志 | 内测 | 使用[OpenTelemetry](https://github.com/open-telemetry/opentelemetry-go)写日志 |
-|[`Friendship`](docs/proposal/22110410-关于Friendship功能项的设计.md) | 关系模式 | 内置 Builtin | 弱关系好友模式，类似微信朋友圈 |
-|[`Followship`](docs/proposal/22110409-关于Followship功能项的设计.md) | 关系模式 | 内置 Builtin | 关注者模式，类似Twitter的Follow模式 |
-|[`Lightship`](docs/proposal/22121409-关于Lightship功能项的设计.md) | 关系模式 | 弃用 Deprecated | 开放模式，所有推文都公开可见 |
-|`Alipay` | 支付 | 稳定 | 开启基于[支付宝开放平台](https://open.alipay.com/)的钱包功能 |
-|`Sms` | 短信验证 | 稳定 | 开启短信验证码功能，用于手机绑定验证手机是否注册者的；功能如果没有开启，手机绑定时任意短信验证码都可以绑定手机 |
-|`Docs:OpenAPI` | 开发文档 | 稳定 | 开启openapi文档功能，提供web api文档说明(visit http://127.0.0.1:8008/docs/openapi) |
-|[`Pyroscope`](docs/proposal/23021510-关于使用pyroscope用于性能调试的设计.md)| 性能优化 | 内测 | 开启Pyroscope功能用于性能调试 |   
-|[`Pprof`](docs/proposal/23062905-添加Pprof功能特性用于获取Profile.md)| 性能优化 | 内测 | 开启Pprof功能收集Profile信息 |  
-|`PhoneBind` | 其他 | 稳定 | 手机绑定功能 |   
-|`UseAuditHook` | 其他 | 内测 | 使用审核hook功能 |   
-|`DisableJobManager` | 其他 | 内测 | 禁止使用JobManager功能 |   
-|`Web:DisallowUserRegister` | 功能特性 | 稳定 | 不允许用户注册 |     
-
-> 功能项状态详情参考 [features-status](features-status.md).
-
-### 源代码分支管理 
-**主代码库`github.com/rocboss/paopao-ce`**      
-```bash
-git branch
-main
-beta
-alpha
-dev
-jc/alimy
-jc/orziz
-r/paopao-ce
-r/paopao-pro
-r/paopao-plus
-r/paopao-xtra
-r/paopao-mini
-```
-**分支说明**  
-| 名称 | 说明 | 备注|
-| ----- | ----- | ----- |       
-| [`main`](https://github.com/rocboss/paopao-ce) | 主分支 |分支`main`是主分支，也是paopao-ce的稳定版本发布分支，只有经过内部测试，没有重大bug出现的稳定代码才会推进到这个分支；该分支主要由`beta`分支代码演进而来，原则上**只接受bug修复PR**。`rc版本/稳定版本` 发布都应该在`main`主分支中进行。|
-| [`beta`](https://github.com/rocboss/paopao-ce/tree/beta) | 公测分支 |分支`beta`是公测分支，代码推进到`main`主分支的候选分支；该分支主要由`alpha`分支代码演进而来，**接受bug修复以及新功能优化的PR**，原则上不接受新功能PR。`beta版本` 发布都应该在`beta`公测分支下进行。|
-| [`alpha`](https://github.com/rocboss/paopao-ce/tree/alpha) | 内测分支 |分支`alpha`是内测分支，代码推进到`beta`分支的候选分支；该分支主要由`dev`分支代码演进而来，**接受bug修复以及新功能相关的PR**，接受新功能PR。分支代码演进到一个里程碑式的阶段后**冻结所有新功能**，合并代码到`beta`公测分支进行下一阶段的持续演进。`alpha版本` 发布都应该在`alpha`内测分支下进行。|   
-| [`dev`](https://github.com/rocboss/paopao-ce/tree/dev) | 开发分支 | 分支`dev`是开发分支，**不定期频繁更新**，接受 *新功能PR、代码优化PR、bug修复PR*；**新功能PR** 都应该首先提交给`dev`分支进行合并，bug修复/新功能开发/代码优化 **阶段性冻结** 后将代码演进合并到`alpha`分支。|   
-| `feature/*` | 子功能分支 |`feature/*`是新功能子分支，一般新功能子分支都是 *从`dev`开发分支fork出来的*；子功能分支 **只专注于该新功能** 代码的开发/优化，待开发接近内测阶段 *提交新功能PR给`dev`分支进行review/merge*，待新功能代码演进到`beta`分支后，原则上是可以删除该分支，但也可以保留到稳定版本发布。**该分支专注于新功能的开发，只接受新功能的bug修复/优化PR**。|
-| `jc/*` |维护者的开发分支|`jc/*`是代码库维护者的开发分支，一般包含一些局部优化或者bug修复代码，有时可以直接将代码merge到`dev/beta`分支，原则上不允许直接merge代码到`main`主分支。|
-| `x/*` |实验分支|`x/*`是技术实验分支，某些技术的引入需要经过具体的代码实现与真实场景的测评，考量评估后如果某项技术适合引入到paopao-ce，就fork出一个`feature/*`分支，作为新功能引入到paopao-ce。一般一些比较激进的技术，从`dev`分支fork出一个新的`x/*`分支，各种尝试、考量、评估后，或丢弃、或引入到paopao-ce。|   
-| `t/*` | 临时分支 |`t/*`是临时发版本分支，一般 `beta` 分支演进到正式版本发布前的最后某个beta版本（比如v0.2.0-beta)就从beta分支fork出一个 `t/*` 分支用于向 `main` 分支提交 PR 用于Review，待 PR Reviewed 合并到 `main` 分支后，可以删除这个临时创建的分支。这样设计主要是考虑到有时合并到 `main` 分支时，需要Review的时间可能会长一些，而dev分支的代码又急需推进到beta分支以发布下一个alpha版本用于内测，相当于为下一个测试版本发布腾地方。|  
-| `r/*` |发行版本分支|`r/*`是不同发行版本分支，不同发行版本各有不同的侧重点，可以根据需要选择适合的发行版本。|
-
-**发行版本分支说明**  
-| 名称 | 说明 | 维护者 | 备注 |
-| ----- | ----- | ----- | ----- |   
-|[`paopao-ce`](https://github.com/rocboss/paopao-ce/tree/dev)|paopao-ce 主发行版本|[ROC](https://github.com/rocboss 'ROC')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/dev/internal/dao/jinzhu) 使用[gorm](https://github.com/go-gorm/gorm)作为数据逻辑层的ORM框架，适配MySQL/PostgreSQL/Sqlite3数据库。| 
-|[`r/paopao-ce`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce)|paopao-ce 主分支预览版本|[ROC](https://github.com/rocboss 'ROC')<br/>[北野](https://github.com/alimy 'Michael Li')<br/>[orzi!](https://github.com/orziz 'orziz')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/dev/internal/dao/jinzhu) 使用[gorm](https://github.com/go-gorm/gorm)作为数据逻辑层的ORM框架，适配MySQL/PostgreSQL/Sqlite3数据库。代码较`main`分支新，是主发行版本的前瞻预览版本。|
-|[`r/paopao-ce-plus`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-plus)|paopao-ce-plus 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-plus/internal/dao/sakila) 使用[sqlx](https://github.com/jmoiron/sqlx)作为数据逻辑层的ORM框架，专注于为MySQL/PostgreSQL/Sqlite3使用更优化的查询语句以提升数据检索效率。建议熟悉[sqlx](https://github.com/jmoiron/sqlx)的开发人员可以基于此版本来做 二次开发。|
-|[`r/paopao-ce-pro`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-pro)|paopao-ce-pro 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 [数据逻辑层](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-pro/internal/dao/slonik) 使用[sqlc](https://github.com/kyleconroy/sqlc)作为sql语句生成器自动生成ORM代码，专门针对特定数据库MySQL/PostgreSQL进行查询优化，熟悉[sqlc](https://github.com/kyleconroy/sqlc)的开发人员可以基于此版本来做 二次开发。(另：分支目前只使用[pgx-v5](https://github.com/jackc/pgx)适配了PostgreSQL数据库，后续或许会适配MySQL/TiDB数据库。)|
-|[`r/paopao-ce-xtra`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-xtra)|paopao-ce-xtra 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支 是r/paopao-ce、r/paopao-ce-plus、r/paopao-ce-pro的合集|
-|[`r/paopao-ce-mini`](https://github.com/rocboss/paopao-ce/tree/r/paopao-ce-mini)|paopao-ce-mini 发行版本|[北野](https://github.com/alimy 'Michael Li')|该分支是paopao-ce最小可用版本，专注于个人部署、一键傻瓜式最简部署|
-
-**代码分支演进图**        
-![](docs/proposal/.assets/000-01.png)
-
-### 部署站点信息
-* [官方 paopao.info](https://www.paopao.info)  
-> 具体部署站点信息请查阅 [deployed-sites](./deployed-sites.md 'deployed sites'). 欢迎站长将已部署PaoPao实例的站点信息添加到 [deployed-sites](./deployed-sites.md 'deployed sites') 列表中。
-
-## 👯‍♀️ 贡献
-paopao-ce 是一个利用 *业余时间* 本着 **"Just for fun just do it."** 的心态 *持续有序* **开发/优化/维护**的开源项目，没有KPI考核、没有Roadmap进度压力、没有技术支持日程安排，或许有些许不足之处，但是重在精神可嘉。 借用网络中的话 **"F\*k talk, f\*k of tech innovation, Shut up and show me your code."** 一切都因更好的体验，一切都是为了爱好，一切都在代码里；期待老铁们加入，一起开发、一起折腾、一起快乐。
-
-喜欢的朋友记得给个Star，欢迎贡献PR。  
+For the current implementation status of each feature, see [features-status.md](features-status.md).
+
+## Documentation Map
+
+- [INSTALL.md](INSTALL.md) - installation, Docker usage, and desktop build instructions
+- [INSTALL_ZH.md](INSTALL_ZH.md) - Chinese installation guide
+- [docs/README.md](docs/README.md) - documentation index
+- [docs/README_ZH.md](docs/README_ZH.md) - Chinese documentation index
+- [docs/deploy/](docs/deploy/) - deployment documentation
+- [docs/openapi/](docs/openapi/) - exported API documentation assets
+- [docs/proposal/](docs/proposal/) - design notes and feature proposals
+- [deployed-sites.md](deployed-sites.md) - known deployed instances
+- [ROADMAP.md](ROADMAP.md) - roadmap and planning notes
+
+## Branch Strategy
+
+The project uses a staged branch model:
+
+| Branch | Role |
+| --- | --- |
+| `main` | Stable production branch; bug-fix oriented |
+| `beta` | Public testing branch |
+| `alpha` | Internal testing branch |
+| `dev` | Main development branch for new work |
+| `feature/*` | Focused feature branches |
+| `r/*` | Distribution-oriented release branches |
+
+If you plan to contribute new functionality, target **`dev`** unless the maintainers specify otherwise.
+
+## Contributing
+
+Issues, discussions, and pull requests are welcome. If you want to contribute:
+
+1. Fork the repository.
+2. Create a branch from `dev` for feature work.
+3. Keep changes focused and documented.
+4. Open a PR with context about the problem, approach, and verification.
+
+If you deploy your own instance, consider adding it to [deployed-sites.md](deployed-sites.md).
 
 [![Star History Chart](https://api.star-history.com/svg?repos=rocboss/paopao-ce&type=Date)](https://star-history.com/#rocboss/paopao-ce&Date)
 
 ## License
 
-Distributed under the MIT License. See `LICENSE` for more information.
-
-<!-- MARKDOWN LINKS & IMAGES -->
-[contributors-shield]: https://img.shields.io/github/contributors/rocboss/paopao-ce?style=flat
-[contributors-url]: https://github.com/rocboss/paopao-ce/graphs/contributors
-[goreport-shield]: https://goreportcard.com/badge/github.com/rocboss/paopao-ce
-[goreport-url]: https://goreportcard.com/report/github.com/rocboss/paopao-ce
-[forks-shield]: https://img.shields.io/github/forks/rocboss/paopao-ce?style=flat
-[forks-url]: https://github.com/rocboss/paopao-ce/network/members
-[stars-shield]: https://img.shields.io/github/stars/rocboss/paopao-ce.svg?style=flat
-[stars-url]: https://github.com/rocboss/paopao-ce/stargazers
-[issues-shield]: https://img.shields.io/github/issues/rocboss/paopao-ce.svg?style=flat
-[issues-url]: https://github.com/rocboss/paopao-ce/issues
-[license-shield]: https://img.shields.io/github/license/rocboss/paopao-ce.svg?style=flat
-[license-url]: https://github.com/rocboss/paopao-ce/blob/master/LICENSE.txt
-[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=flat&logo=linkedin&colorB=555
-[product-light-screenshot]: https://assets.paopao.info/static/paopao-light.jpeg
-[product-dark-screenshot]: https://assets.paopao.info/static/paopao-dark.jpeg
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
+
+<p align="right">(<a href="#top">back to top</a>)</p>
diff --git a/README_ZH.md b/README_ZH.md
new file mode 100644
index 00000000..bed01d41
--- /dev/null
+++ b/README_ZH.md
@@ -0,0 +1,243 @@
+<div id="top"></div>
+
+[![Go](https://github.com/rocboss/paopao-ce/actions/workflows/go.yml/badge.svg)](https://github.com/rocboss/paopao-ce/actions/workflows/go.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/rocboss/paopao-ce)](https://goreportcard.com/report/github.com/rocboss/paopao-ce)
+[![Forks](https://img.shields.io/github/forks/rocboss/paopao-ce?style=flat)](https://github.com/rocboss/paopao-ce/network/members)
+[![Stars](https://img.shields.io/github/stars/rocboss/paopao-ce.svg?style=flat)](https://github.com/rocboss/paopao-ce/stargazers)
+[![MIT License](https://img.shields.io/github/license/rocboss/paopao-ce.svg?style=flat)](https://github.com/rocboss/paopao-ce/blob/main/LICENSE)
+[![Contributors](https://img.shields.io/github/contributors/rocboss/paopao-ce?style=flat)](https://github.com/rocboss/paopao-ce/graphs/contributors)
+[![Sourcegraph](https://img.shields.io/badge/view%20on-Sourcegraph-brightgreen.svg)](https://sourcegraph.com/github.com/rocboss/paopao-ce)
+
+<div align="center">
+  <a href="https://github.com/rocboss/paopao-ce">
+    <img src="https://assets.paopao.info/static/paopao-logo.png" alt="PaoPao logo" width="88" height="88">
+  </a>
+
+  <h1 align="center">PaoPao</h1>
+
+  <p align="center">
+    一个基于 Go 与 Vue 的开源微社区平台。
+    <br />
+    适合自部署社区产品、功能验证，以及在现有能力之上进行二次开发。
+  </p>
+
+  <p align="center">
+    <a href="README.md">English</a>
+    ·
+    <a href="https://www.paopao.info/">在线演示</a>
+    ·
+    <a href="https://github.com/rocboss/paopao-ce/pulls">Pull Requests</a>
+    ·
+    <a href="https://www.yuque.com/rocs/paopao/about">项目笔记</a>
+  </p>
+</div>
+
+---
+
+## 项目简介
+
+PaoPao 是一个完整的开源微社区系统，包含 Go 后端、Vue 3 Web 前端，以及可选的 Tauri 桌面端。项目通过模块化的特性开关体系，将存储、搜索、日志、可观测性与部署方式组合在一起，便于按需裁剪和扩展。
+
+如果你希望快速搭建一个可运行的社区产品，或者基于成熟代码库继续定制开发，而不是从零开始，PaoPao 是一个很合适的起点。
+
+## 为什么选择 PaoPao
+
+- **全栈一体化**：后端、Web 前端、桌面端构建都在同一仓库中维护。
+- **模块化运行能力**：通过 `Features` 套件启用不同能力组合，例如 `Default`、`Develop`、`Demo`、`Slim`。
+- **基础设施灵活**：支持 MySQL、PostgreSQL、SQLite、Redis、Meilisearch 以及多种对象存储后端。
+- **部署方式丰富**：可通过源码、Docker、Docker Compose 或 all-in-one 镜像运行。
+- **适合自部署**：配置文件清晰，仓库内已提供部署与开发文档。
+
+## 预览
+
+### Web 端
+
+[![明色主题预览](https://assets.paopao.info/static/paopao-light.jpeg)](https://www.paopao.info)
+
+[![暗色主题预览](https://assets.paopao.info/static/paopao-dark.jpeg)](https://www.paopao.info)
+
+### 桌面端
+
+![](docs/proposal/.assets/000-00.jpg)
+
+更多效果可前往 [paopao.info](https://www.paopao.info/) 查看。
+
+## 架构概览
+
+| 层级 | 主要技术 |
+| --- | --- |
+| 后端 | Go、Gin、Cobra、GORM、Mir |
+| Web 前端 | Vue 3、Vite、Naive UI |
+| 桌面端 | Tauri |
+| 搜索 | Meilisearch |
+| 缓存 | Redis |
+| 对象存储 | Local OSS、MinIO、AliOSS、COS、Huawei OBS、S3 兼容存储 |
+| 可观测性 | OpenTelemetry、Sentry、Pyroscope、Pprof |
+
+## 仓库结构
+
+| 路径 | 说明 |
+| --- | --- |
+| `cmd/`、`internal/`、`pkg/` | 后端应用与共享包 |
+| `web/` | Vue 3 Web 应用与 Tauri 桌面端前端 |
+| `docs/` | 部署文档、OpenAPI 文档、设计提案等 |
+| `scripts/` | SQL 初始化脚本与辅助资源 |
+| `config.yaml.sample` | 完整的运行配置模板 |
+
+## 快速开始
+
+### 方案 A：使用 Docker Compose 快速体验
+
+这是本地体验项目的最快方式。
+
+```sh
+git clone https://github.com/rocboss/paopao-ce.git
+cd paopao-ce
+docker compose up -d
+```
+
+启动后可访问：
+
+- `http://localhost:8008` - PaoPao
+- `http://localhost:7700` - Meilisearch
+- `http://localhost:8001` - RedisInsight
+
+### 方案 B：从源码开发
+
+#### 环境要求
+
+- Go `1.24+`
+- Node.js `20.19+` 或 `22.12+`
+- MySQL `5.7+`
+- Redis
+- Meilisearch
+- 如果需要构建桌面端，还需要安装 Rust 与 Tauri 依赖
+
+#### 后端
+
+1. 将 `scripts/paopao-mysql.sql` 导入 MySQL。
+2. 复制示例配置并按本地环境调整。
+3. 启动后端服务。
+
+```sh
+cp config.yaml.sample config.yaml
+make run
+```
+
+如果需要构建发布二进制：
+
+```sh
+make build
+```
+
+如果希望由 Go 服务直接内嵌并提供 Web UI，请先构建前端资源，再使用 `embed` 标签启动：
+
+```sh
+make build-web
+make run TAGS='embed'
+```
+
+#### Web 前端
+
+```sh
+cd web
+cp .env .env.local
+yarn
+yarn dev
+```
+
+构建静态资源：
+
+```sh
+yarn build
+```
+
+#### 桌面端
+
+```sh
+cd web
+yarn tauri build
+```
+
+更完整的安装步骤、Docker 构建方式、桌面端依赖与 migration 说明，请参考 [INSTALL_ZH.md](INSTALL_ZH.md)。
+
+## 配置与 Feature 套件
+
+`config.yaml.sample` 是项目的标准配置模板。运行时，PaoPao 会读取 `./custom/config.yaml` 或 `./config.yaml`，并优先使用先找到的文件。
+
+`Features` 配置用于控制启用哪些能力组合：
+
+```yaml
+Features:
+  Default: ["Base", "MySQL", "Option", "LocalOSS", "LoggerFile"]
+  Develop: ["Base", "MySQL", "Option", "Sms", "AliOSS", "LoggerOtlp"]
+  Demo: ["Base", "MySQL", "Option", "Sms", "MinIO", "LoggerOtlp"]
+  Slim: ["Base", "Sqlite3", "LocalOSS", "LoggerFile"]
+  Base: ["Zinc", "Redis", "Alipay"]
+  Option: ["SimpleCacheIndex"]
+  Sms: "SmsJuhe"
+```
+
+常见用法示例：
+
+```sh
+# 使用默认套件
+release/paopao serve
+
+# 仅使用 develop 中声明的功能集
+release/paopao serve --no-default-features --features develop
+
+# 在默认套件基础上增加 sms
+release/paopao serve --features sms
+
+# 手动显式指定功能项
+release/paopao serve --no-default-features --features sqlite3,localoss,loggerfile,redis
+```
+
+各功能项的当前实现状态可参考 [features-status.md](features-status.md)。
+
+## 文档导航
+
+- [INSTALL_ZH.md](INSTALL_ZH.md) - 中文安装、Docker 使用与桌面端构建说明
+- [INSTALL.md](INSTALL.md) - English installation guide
+- [docs/README_ZH.md](docs/README_ZH.md) - 中文文档总索引
+- [docs/README.md](docs/README.md) - English documentation index
+- [docs/deploy/](docs/deploy/) - 部署相关文档
+- [docs/openapi/](docs/openapi/) - 导出的 API 文档资源
+- [docs/proposal/](docs/proposal/) - 设计说明与功能提案
+- [deployed-sites.md](deployed-sites.md) - 已知部署站点列表
+- [ROADMAP.md](ROADMAP.md) - 路线图与规划说明
+
+## 分支策略
+
+项目采用分阶段分支模型：
+
+| 分支 | 作用 |
+| --- | --- |
+| `main` | 稳定生产分支，主要接收缺陷修复 |
+| `beta` | 公测分支 |
+| `alpha` | 内测分支 |
+| `dev` | 主要开发分支，适合新功能开发 |
+| `feature/*` | 独立功能分支 |
+| `r/*` | 面向不同发行形态的发布分支 |
+
+如果你准备提交新功能，通常应优先向 **`dev`** 分支发起贡献。
+
+## 参与贡献
+
+欢迎提交 Issue、讨论和 Pull Request。建议的贡献流程：
+
+1. Fork 当前仓库。
+2. 从 `dev` 分支拉出自己的功能分支。
+3. 保持改动聚焦，并补充必要文档。
+4. 提交 PR 时说明问题背景、实现方式与验证结果。
+
+如果你已经部署了自己的实例，也欢迎将站点补充到 [deployed-sites.md](deployed-sites.md)。
+
+[![Star History Chart](https://api.star-history.com/svg?repos=rocboss/paopao-ce&type=Date)](https://star-history.com/#rocboss/paopao-ce&Date)
+
+## License
+
+项目基于 MIT License 发布，详见 [LICENSE](LICENSE)。
+
+<p align="right">(<a href="#top">回到顶部</a>)</p>
diff --git a/docs/README.md b/docs/README.md
index fda64147..951deb0b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,7 +1,44 @@
-## 开发文档
-本目录包含一些开发者文档。
+# Documentation Index
 
-* [openapi](openapi): api相关文档
-* [proposal](proposal): 开发/设计 提按相关文档
-* [deploy](deploy): 部署相关文档
-* [discuss](discuss): 开发者交流
+English | [简体中文](README_ZH.md)
+
+This directory contains project documentation for development, deployment, API assets, design notes, and community discussions around PaoPao.
+
+If you are looking for the main project entry points, start from:
+
+- [../README.md](../README.md) - project overview
+- [../INSTALL.md](../INSTALL.md) - installation and local setup guide
+
+## Documentation Sections
+
+| Section | Description |
+| --- | --- |
+| [openapi/](openapi/) | Exported API documentation assets, including generated OpenAPI files and static docs artifacts |
+| [proposal/](proposal/) | Product ideas, design proposals, and implementation notes |
+| [deploy/](deploy/) | Deployment references for local, cloud, and Kubernetes environments |
+| [discuss/](discuss/) | Discussion-oriented documents, notes, and related references |
+
+## Recommended Reading Paths
+
+### New contributors
+
+1. Read [../README.md](../README.md)
+2. Follow [../INSTALL.md](../INSTALL.md)
+3. Browse [proposal/](proposal/) to understand product intent and feature direction
+
+### Operators and self-hosters
+
+1. Start with [../INSTALL.md](../INSTALL.md)
+2. Continue into [deploy/README.md](deploy/README.md)
+3. Use the platform-specific deployment docs that match your target environment
+
+### API and integration work
+
+1. Review [openapi/](openapi/)
+2. Check [proposal/](proposal/) for feature context when endpoint behavior is tied to product design
+
+## Notes
+
+- `openapi/` is primarily a generated documentation asset bundle rather than a hand-written narrative section.
+- `proposal/` contains historical and ongoing design material, so some documents reflect exploration rather than final behavior.
+- `discuss/` may include working notes and community-oriented references in addition to formal documentation.
diff --git a/docs/README_ZH.md b/docs/README_ZH.md
new file mode 100644
index 00000000..ac2c5a65
--- /dev/null
+++ b/docs/README_ZH.md
@@ -0,0 +1,44 @@
+# 文档索引
+
+[English](README.md) | 简体中文
+
+本目录汇总了 PaoPao 的开发文档、部署文档、API 文档资源、设计提案以及讨论性资料。
+
+如果你想先从项目主入口开始，建议优先阅读：
+
+- [../README_ZH.md](../README_ZH.md) - 项目总览
+- [../INSTALL_ZH.md](../INSTALL_ZH.md) - 安装与本地部署指南
+
+## 文档分区
+
+| 分区 | 说明 |
+| --- | --- |
+| [openapi/](openapi/) | 导出的 API 文档资源，包含生成的 OpenAPI 文件与静态文档产物 |
+| [proposal/](proposal/) | 产品设计、功能提案与实现思路说明 |
+| [deploy/](deploy/) | 本地、云平台与 Kubernetes 等部署参考文档 |
+| [discuss/](discuss/) | 偏讨论性质的文档、记录与相关资料 |
+
+## 推荐阅读路径
+
+### 新贡献者
+
+1. 先阅读 [../README_ZH.md](../README_ZH.md)
+2. 再参考 [../INSTALL_ZH.md](../INSTALL_ZH.md)
+3. 最后浏览 [proposal/](proposal/) 了解产品定位与功能方向
+
+### 运维与自部署使用者
+
+1. 从 [../INSTALL_ZH.md](../INSTALL_ZH.md) 开始
+2. 继续阅读 [deploy/README_ZH.md](deploy/README_ZH.md)
+3. 再进入与你目标环境对应的平台部署文档
+
+### API 与集成开发
+
+1. 先查看 [openapi/](openapi/)
+2. 如果接口行为与产品设计相关，再结合 [proposal/](proposal/) 理解背景
+
+## 说明
+
+- `openapi/` 更偏向生成产物目录，而不是纯手写说明文档。
+- `proposal/` 中既有历史设计稿，也有仍具参考价值的设计说明，因此不一定全部代表最终实现。
+- `discuss/` 中可能包含更偏工作记录或社区讨论性质的内容。
diff --git a/docs/deploy/README.md b/docs/deploy/README.md
index cedbe93f..bf0b5eec 100644
--- a/docs/deploy/README.md
+++ b/docs/deploy/README.md
@@ -1,9 +1,50 @@
-## 部署文档
-本目录包含一些paopao-ce部署相关的帮助文档
-
-* [core](./core) - paopao-ce部署帮助文档
-* [aliyun](./aliyun) - Aliyun平台部署文档
-* [huawei](./huawei) - Huawei Cloud平台部署文档
-* [tencnet](./tencent) - Tencent Cloud平台部署文档
-* [local](./local) - 本地部署文档
-* [k8s](./k8s) - 使用Kubernetes部署paopao-ce相关文档
+# Deployment Documentation
+
+English | [简体中文](README_ZH.md)
+
+This directory collects deployment-oriented documentation for PaoPao across local environments, cloud platforms, and Kubernetes-based setups.
+
+For the higher-level setup flow, start with:
+
+- [../../INSTALL.md](../../INSTALL.md) - installation and runtime setup guide
+- [../README.md](../README.md) - overall documentation index
+
+## Deployment Sections
+
+| Section | Description |
+| --- | --- |
+| [core/](core/) | Core deployment concepts and configuration references |
+| [local/](local/) | Local deployment and local dependency setup notes |
+| [aliyun/](aliyun/) | Alibaba Cloud deployment documentation |
+| [huawei/](huawei/) | Huawei Cloud deployment documentation |
+| [tencent/](tencent/) | Tencent Cloud deployment documentation |
+| [k8s/](k8s/) | Kubernetes deployment references |
+
+## Suggested Reading Order
+
+### For local self-hosting
+
+1. Read [../../INSTALL.md](../../INSTALL.md)
+2. Continue with [local/README.md](local/README.md)
+3. Use [core/](core/) if you need additional configuration detail
+
+### For cloud deployment
+
+1. Read [../../INSTALL.md](../../INSTALL.md)
+2. Review [core/](core/)
+3. Open the provider-specific guide for your target platform:
+   - [aliyun/README.md](aliyun/README.md)
+   - [huawei/README.md](huawei/README.md)
+   - [tencent/README.md](tencent/README.md)
+
+### For Kubernetes-based deployment
+
+1. Read [../../INSTALL.md](../../INSTALL.md)
+2. Review [core/](core/)
+3. Continue with [k8s/README.md](k8s/README.md)
+
+## Notes
+
+- Some platform directories primarily contain a single README with environment-specific instructions.
+- `local/` includes additional assets such as local dependency notes and example config material.
+- When deployment behavior depends on enabled runtime features, align your infrastructure choices with `config.yaml` and the selected `Features` suite.
diff --git a/docs/deploy/README_ZH.md b/docs/deploy/README_ZH.md
new file mode 100644
index 00000000..56909bd8
--- /dev/null
+++ b/docs/deploy/README_ZH.md
@@ -0,0 +1,50 @@
+# 部署文档索引
+
+[English](README.md) | 简体中文
+
+本目录汇总了 PaoPao 在本地环境、云平台以及 Kubernetes 场景下的部署文档。
+
+如果你需要先了解完整安装流程，建议先阅读：
+
+- [../../INSTALL_ZH.md](../../INSTALL_ZH.md) - 安装与运行配置指南
+- [../README_ZH.md](../README_ZH.md) - 文档总索引
+
+## 部署分区
+
+| 分区 | 说明 |
+| --- | --- |
+| [core/](core/) | 部署基础概念与核心配置说明 |
+| [local/](local/) | 本地部署与本地依赖环境说明 |
+| [aliyun/](aliyun/) | 阿里云部署文档 |
+| [huawei/](huawei/) | 华为云部署文档 |
+| [tencent/](tencent/) | 腾讯云部署文档 |
+| [k8s/](k8s/) | Kubernetes 部署参考 |
+
+## 推荐阅读顺序
+
+### 本地自部署
+
+1. 先阅读 [../../INSTALL_ZH.md](../../INSTALL_ZH.md)
+2. 再查看 [local/README.md](local/README.md)
+3. 如果需要更细的配置说明，再进入 [core/](core/)
+
+### 云平台部署
+
+1. 先阅读 [../../INSTALL_ZH.md](../../INSTALL_ZH.md)
+2. 再查看 [core/](core/)
+3. 最后进入对应平台文档：
+   - [aliyun/README.md](aliyun/README.md)
+   - [huawei/README.md](huawei/README.md)
+   - [tencent/README.md](tencent/README.md)
+
+### Kubernetes 部署
+
+1. 先阅读 [../../INSTALL_ZH.md](../../INSTALL_ZH.md)
+2. 再查看 [core/](core/)
+3. 最后阅读 [k8s/README.md](k8s/README.md)
+
+## 说明
+
+- 某些平台目录主要只有一个 README 文件，集中说明该平台的部署步骤。
+- `local/` 目录中除了说明文档外，还包含本地依赖环境说明与示例配置材料。
+- 如果部署方式依赖特定 Feature 组合，请确保基础设施与 `config.yaml` 中启用的 `Features` 保持一致。