浅浅升级一下

docs/environment-variables.md

@@ -138,6 +138,33 @@
 | `JUNHONG_QUEUE_RETRY_MAX` | `3` | 最大重试次数 |
 | `JUNHONG_QUEUE_TIMEOUT` | `30m` | 任务超时时间 |
 
+### Worker 运行配置
+
+| 环境变量 | 默认值 | 说明 |
+|---------|--------|------|
+| `JUNHONG_WORKER_ROLE` | `all` | Worker 运行角色。`all` 为单实例兼容模式，`leader` 负责主动调度和初始化，`consumer` 只消费队列任务 |
+| `JUNHONG_WORKER_INSTANCE_NAME` | `""` | Worker 实例名称，用于多实例日志区分，建议在多实例部署时配置唯一值 |
+
+**使用说明**：
+- 单实例部署可不设置 `JUNHONG_WORKER_ROLE`，默认使用 `all`，行为与历史版本一致
+- 多实例部署推荐固定 `1 leader + N consumer`
+- `leader` / `all` 只能保留一个实例承担主动调度职责，横向扩容时请新增 `consumer`
+
+**示例**：
+
+```bash
+# 单实例兼容模式（默认可省略）
+JUNHONG_WORKER_ROLE=all
+
+# 多实例 leader
+JUNHONG_WORKER_ROLE=leader
+JUNHONG_WORKER_INSTANCE_NAME=worker-leader-1
+
+# 多实例 consumer
+JUNHONG_WORKER_ROLE=consumer
+JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-1
+```
+
 ### 限流中间件
 
 | 环境变量 | 默认值 | 说明 |
@@ -220,6 +247,8 @@ services:
       - JUNHONG_DATABASE_DBNAME=junhong_cmp
       - JUNHONG_REDIS_ADDRESS=redis
       - JUNHONG_JWT_SECRET_KEY=your-production-secret-key
+      - JUNHONG_WORKER_ROLE=all
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-all-1
     volumes:
       - ./logs:/app/logs
 
@@ -234,6 +263,51 @@ services:
     image: redis:6
 ```
 
+- 单实例部署默认就是 `all`，上例显式写出只是为了便于排查日志；不设置 `JUNHONG_WORKER_ROLE` 时效果相同
+- 多实例部署推荐 `1 leader + N consumer`，不要直接复制多个完整 `all` Worker
+
+```yaml
+services:
+  worker-leader:
+    image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
+    environment:
+      - JUNHONG_DATABASE_HOST=postgres
+      - JUNHONG_DATABASE_PORT=5432
+      - JUNHONG_DATABASE_USER=junhong
+      - JUNHONG_DATABASE_PASSWORD=secret123
+      - JUNHONG_DATABASE_DBNAME=junhong_cmp
+      - JUNHONG_REDIS_ADDRESS=redis
+      - JUNHONG_JWT_SECRET_KEY=your-production-secret-key
+      - JUNHONG_WORKER_ROLE=leader
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-leader-1
+
+  worker-consumer-1:
+    image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
+    environment:
+      - JUNHONG_DATABASE_HOST=postgres
+      - JUNHONG_DATABASE_PORT=5432
+      - JUNHONG_DATABASE_USER=junhong
+      - JUNHONG_DATABASE_PASSWORD=secret123
+      - JUNHONG_DATABASE_DBNAME=junhong_cmp
+      - JUNHONG_REDIS_ADDRESS=redis
+      - JUNHONG_JWT_SECRET_KEY=your-production-secret-key
+      - JUNHONG_WORKER_ROLE=consumer
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-1
+
+  worker-consumer-2:
+    image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
+    environment:
+      - JUNHONG_DATABASE_HOST=postgres
+      - JUNHONG_DATABASE_PORT=5432
+      - JUNHONG_DATABASE_USER=junhong
+      - JUNHONG_DATABASE_PASSWORD=secret123
+      - JUNHONG_DATABASE_DBNAME=junhong_cmp
+      - JUNHONG_REDIS_ADDRESS=redis
+      - JUNHONG_JWT_SECRET_KEY=your-production-secret-key
+      - JUNHONG_WORKER_ROLE=consumer
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-2
+```
+
 ## 本地开发
 
 本地开发可以创建 `.env` 文件（不要提交到 Git）：

docs/polling-system/performance-tuning.md

@@ -44,26 +44,35 @@ INSERT INTO tb_polling_concurrency_config (task_type, max_concurrency, descripti
 
 ### 3. Worker 多实例部署
 
-部署多个 Worker 实例分担负载：
+多实例扩容时，必须拆分 Worker 角色，禁止直接复制多个完整 Worker 进程。推荐保留 `1 leader + N consumer`：
 
 ```yaml
 # docker-compose.yml 示例
 services:
-  worker-1:
+  worker-leader:
     image: junhong-cmp-worker
     environment:
-      - WORKER_ID=1
-  worker-2:
+      - JUNHONG_WORKER_ROLE=leader
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-leader-1
+  worker-consumer-1:
     image: junhong-cmp-worker
     environment:
-      - WORKER_ID=2
-  worker-3:
+      - JUNHONG_WORKER_ROLE=consumer
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-1
+  worker-consumer-2:
     image: junhong-cmp-worker
     environment:
-      - WORKER_ID=3
+      - JUNHONG_WORKER_ROLE=consumer
+      - JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-2
 ```
 
-注意：只需一个实例运行调度器，其他实例只处理任务。
+说明：
+- `leader` 负责轮询初始化、轮询调度、Asynq 定时任务调度等单例职责
+- `consumer` 只负责 Asynq 队列消费，适合横向扩容
+- 单实例部署默认使用 `all`，行为等价于历史版本
+- 不要直接启动多个 `all` 或多个 `leader`，否则会重复扫库、重复调度、重复入队
+- 需要提升吞吐时，优先增加 `consumer` 数量，而不是复制完整 Worker
+- 本期仅完成角色拆分，不包含 Redis Leader 锁、自动选主、任务唯一性去重，这些作为第二期增强处理
 
 ### 4. 检查间隔优化