This is an automated email from the ASF dual-hosted git repository.
jinrongtong pushed a commit to branch new-official-website
in repository https://gitbox.apache.org/repos/asf/rocketmq-site.git
The following commit(s) were added to refs/heads/new-official-website by this
push:
new 9055378e07 [ISSUE #748] Add ACL 2.0 document (#749)
9055378e07 is described below
commit 9055378e073ce09495b0c7c28dcab22066ccf660
Author: dingshuangxi888 <[email protected]>
AuthorDate: Mon Nov 24 11:49:09 2025 +0800
[ISSUE #748] Add ACL 2.0 document (#749)
* add rocketmq acl 2.0 document
Change-Id: I014bcea2b798dc4a9f668f6917bc4f23580c65e4
Co-developed-by: Cursor <[email protected]>
* 删除一些多余的文档
Change-Id: I37b66feead00e92817a77b11e63bf81b8f50cba2
Co-developed-by: Cursor <[email protected]>
* 添加提示信息
Change-Id: I4a8c18b764fa8d6eccba729df351a0ffc34b52e5
Co-developed-by: Cursor <[email protected]>
* add warning info
Change-Id: I9a2babdc50d09bfe1f652ada1658f1f92ea5e85f
Co-developed-by: Cursor <[email protected]>
* modify warning info
Change-Id: I79a3e483d785ae8b6e06789db36bbd72f8a06b85
Co-developed-by: Cursor <[email protected]>
* delete architecture comparison
Change-Id: I939cb449511de173db4b163acc3c6878cc144fa8
Co-developed-by: Cursor <[email protected]>
* modify warning info
Change-Id: I6eb1612441e73e85c5aa78fa8f77e02374007612
Co-developed-by: Cursor <[email protected]>
* optimize access.md
Change-Id: I0fab7cf5aae07e0f80361c6d03bd8e606fc46a04
Co-developed-by: Cursor <[email protected]>
* optimize access.md
Change-Id: Iebba9a7a8941e6739a73f7c9333d1107730bb843
Co-developed-by: Cursor <[email protected]>
* optimize access.md
Change-Id: I955555200441df2b262410bb514ec36e16af6907
Co-developed-by: Cursor <[email protected]>
* optimize access.md
Change-Id: I1976a2c7e421fb573704f6767b7f361a9b30c0a1
Co-developed-by: Cursor <[email protected]>
* add english version of access.md
Change-Id: Iba57d73b5d78241eaa66e170bef1d370ab8f47c8
Co-developed-by: Cursor <[email protected]>
* optimize access.md
Change-Id: I402292ca855031bc7cedb7f628e5d0da4262ca54
Co-developed-by: Cursor <[email protected]>
* fix: access-1.0.md
Change-Id: I600ac4a5d0458cae6c7cb0b49c481dacd45360c8
Co-developed-by: Cursor <[email protected]>
---------
Co-authored-by: shuangxi.dsx <[email protected]>
---
.../version-5.0/06-bestPractice/03access.md | 1296 ++++++++++++++++++--
.../{03access.md => 07access-1.0.md} | 16 +-
.../version-5.0/06-bestPractice/03access.md | 1277 ++++++++++++++++---
.../{03access.md => 07access-1.0.md} | 23 +-
4 files changed, 2341 insertions(+), 271 deletions(-)
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
index e580147747..92e9848c02 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
@@ -1,191 +1,1235 @@
-# Access Control
+# RocketMQ ACL 2.0 User Guide
-## 1. Introduction to access control features
+:::info Version Notice
-access control (ACL) mainly provides advanced access control functions at the
Topic resource level for RocketMQ. When using RocketMQ access control, users
can inject user name and password parameters into the client to achieve
signature, and the server can implement permission management and verification
of various resources through access control parameters.
+This document describes **RocketMQ ACL 2.0**, applicable to **RocketMQ 5.3.0**
and above.
-:::info
+- If you are using **RocketMQ 4.x, 5.0-5.2, or 5.3.0-5.3.2**, please refer to
[ACL 1.0 Documentation](07access-1.0.md)
+- **Starting from RocketMQ 5.3.3, ACL 1.0 is no longer supported**. It is
recommended to upgrade to ACL 2.0
+- If you are migrating from ACL 1.0 to 2.0, please refer to the [ACL 1.0
Migration](#migrating-from-acl-10-to-acl-20) section
-ACL control will increase the complexity of deployment process and operation
and maintenance management while enhancing cluster access control security. It
is generally only recommended for use in scenarios where the network
environment is not secure, business data is sensitive, and multiple departments
and tenants are mixed. If the production cluster itself is a private cluster
and is not accessed by external departments and tenants, it can be turned off.
+:::
+
+:::danger Security Notice
+
+⚠️ **All usernames and passwords in this document are for demonstration
purposes only. DO NOT use them in production environments!**
+
+For production deployment, please ensure:
+- Use strong passwords (at least 16 characters, including uppercase,
lowercase, numbers, and special characters)
+- Strictly control the scope of super user usage
+- Properly secure authentication credentials and do not commit them in plain
text to code repositories
:::
-## 2. Definition and attribute values of access control
+## Introduction
+
+### What is RocketMQ ACL 2.0?
+
+RocketMQ ACL 2.0 is an upgraded version of Apache RocketMQ's Access Control
List, providing comprehensive authentication and authorization mechanisms to
protect the data security of RocketMQ clusters.
+
+### Core Features
+
+- **Dual Security Mechanisms**: Supports independent configuration of
authentication and authorization
+- **Flexible Resource Matching**: Supports exact match, prefix match, and
wildcard match
+- **Fine-grained Permission Control**: Covers multiple resource types
including Cluster, Namespace, Topic, and Group
+- **Multiple Strategy Options**: Provides stateless and stateful
authentication/authorization strategies
+- **Inter-component Secure Communication**: Supports access control between
components such as Broker, Proxy, and NameServer
+
+### Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **User** | Entity accessing RocketMQ resources, divided into Super users and
Normal users |
+| **Resource** | Objects requiring access control, such as Cluster, Namespace,
Topic, Group |
+| **Action** | Operations performed on resources, such as Pub, Sub, Create,
Update, Delete, Get, List |
+| **Decision** | Authorization result, Allow or Deny |
+| **Environment** | Access environment information, such as source IP address |
+
+---
+
+## Quick Start
+
+### 5-Minute Quick Experience
+
+This section helps you quickly start a RocketMQ cluster with ACL enabled in 5
minutes.
+
+> **Prerequisites**:
+> - RocketMQ version ≥ 5.3.0
+> - RocketMQ basic installation completed
+>
+> **Version Check**:
+> ```bash
+> # Check RocketMQ version
+> sh bin/mqbroker -v
+> ```
+
+> **Note**: This example uses integrated storage-compute architecture (single
Broker mode), suitable for quick experience and testing environments. For
production deployment, refer to the [Configuration](#configuration) section.
+
+#### Step 1: Configure Broker
+
+Edit the `conf/broker.conf` file and add the following configuration:
+
+```properties
+# Enable authentication
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+
+# Enable authorization
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+
+# Initialize admin user (auto-created on first startup)
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+
+# Inter-component authentication credentials (for Broker master-slave sync,
internal cluster communication, etc.)
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+> **Configuration Notes**:
+> - Only required items need to be configured for quick start; other items
have default values
+> - For production environments, it is recommended to configure
`authenticationStrategy` and `authorizationStrategy` to stateful strategy for
better performance
+
+#### Step 2: Start Cluster
+
+```bash
+# 1. Start NameServer
+nohup sh bin/mqnamesrv &
+
+# 2. Start Broker (using the above configuration file)
+nohup sh bin/mqbroker -n localhost:9876 -c conf/broker.conf &
+```
+
+#### Step 3: Configure mqadmin Tool
+
+After enabling ACL, you need to configure authentication credentials for the
mqadmin tool to execute management commands.
+
+Edit the `conf/tools.yml` file:
+
+```yaml
+# Use the initialized admin user credentials
+accessKey: rocketmq
+secretKey: 12345678
+```
+
+#### Step 4: Create Business Users and Grant Permissions
+
+```bash
+# Create producer user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u producer_user \
+ -p producer123 \
+ -t Normal
+
+# Grant Topic publish permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user \
+ -r Topic:TestTopic \
+ -a Pub \
+ -d Allow
+```
+
+#### Step 5: Verify Configuration
+
+Send a test message using Java client:
+
+```java
+SessionCredentials credentials = new SessionCredentials("producer_user",
"producer123");
+StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:10911")
+ .setCredentialProvider(credentialsProvider)
+ .build();
+// ... Create Producer and send message
+```
+
+✅ Congratulations! You have successfully started a RocketMQ cluster with ACL
enabled.
+
+### Different Deployment Architecture Configurations
+
+RocketMQ supports two deployment architectures. Choose the appropriate
configuration based on your scenario.
+
+#### Integrated Storage-Compute Architecture
+
+Broker handles both computation and storage, suitable for small to
medium-scale clusters and testing environments.
+
+**Configuration Example**:
+
+```properties
+# broker.conf
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+#### Separated Storage-Compute Architecture (Recommended)
+
+Proxy handles computation and authentication/authorization, while Broker only
handles storage and metadata management. Suitable for large-scale production
environments.
+
+**Broker Configuration** (`broker.conf`):
+
+```properties
+# Broker only acts as metadata provider, does not handle client
authentication/authorization
+authenticationEnabled = false
+authorizationEnabled = false
+
+# Configure metadata providers
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+
+# Initialize admin user
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+```
+
+**Proxy Configuration** (`rmq-proxy.json`):
+
+```json
+{
+ "authenticationEnabled": true,
+ "authenticationProvider":
"org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider",
+ "authenticationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthenticationMetadataProvider",
+ "authenticationStrategy":
"org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy",
+
+ "authorizationEnabled": true,
+ "authorizationProvider":
"org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider",
+ "authorizationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthorizationMetadataProvider",
+ "authorizationStrategy":
"org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy"
+}
+```
+
+**Startup Sequence**:
+
+```bash
+# 1. Start NameServer
+nohup sh bin/mqnamesrv &
+
+# 2. Start Broker (storage node)
+nohup sh bin/mqbroker -n localhost:9876 -c conf/broker.conf &
+
+# 3. Start Proxy (compute node)
+nohup sh bin/mqproxy -n localhost:9876 -pc conf/rmq-proxy.json &
+```
+
+---
+
+## Configuration
+
+### Authentication Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `authenticationEnabled` | boolean | `false` | Whether to enable
authentication |
+| `authenticationProvider` | String |
`org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider`
| Authentication provider implementation class (optional, uses default) |
+| `authenticationMetadataProvider` | String | - | Authentication metadata
provider implementation class<br/>**Required** |
+| `authenticationStrategy` | String |
`org.apache.rocketmq.auth.authentication.strategy.StatelessAuthenticationStrategy`
| Authentication strategy (optional, uses default)<br/>Production
recommendation: stateful
strategy<br/>`org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy`
|
+| `initAuthenticationUser` | JSON | - | **Recommended**: System initialization
user (auto-created on first startup)<br/>Format:
`{"username":"xxx","password":"xxx"}`<br/>If not configured, admin user must be
created manually |
+| `innerClientAuthenticationCredentials` | JSON | - | **Conditional**:
Inter-component authentication credentials for Broker master-slave sync,
Proxy-Broker access, Controller election, etc.<br/>Format:
`{"accessKey":"xxx","secretKey":"xxx"}`<br/>⚠️ All components must use
identical credentials if inter-component communication exists |
+| `authenticationWhitelist` | String | - | Authentication whitelist
(comma-separated IP list) |
+
+### Authorization Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `authorizationEnabled` | boolean | `false` | Whether to enable authorization
|
+| `authorizationProvider` | String |
`org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider`
| Authorization provider implementation class (optional, uses default) |
+| `authorizationMetadataProvider` | String | - | Authorization metadata
provider implementation class<br/>**Required** |
+| `authorizationStrategy` | String |
`org.apache.rocketmq.auth.authorization.strategy.StatelessAuthorizationStrategy`
| Authorization strategy (optional, uses default)<br/>Production
recommendation: stateful
strategy<br/>`org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy`
|
+| `authorizationWhitelist` | String | - | Authorization whitelist
(comma-separated IP list) |
+
+### Cache Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `userCacheMaxNum` | int | `1000` | Maximum user cache size |
+| `userCacheExpiredSecond` | int | `600` | User cache expiration time
(seconds) |
+| `userCacheRefreshSecond` | int | `60` | User cache refresh time (seconds) |
+| `aclCacheMaxNum` | int | `1000` | Maximum ACL cache size |
+| `aclCacheExpiredSecond` | int | `600` | ACL cache expiration time (seconds) |
+| `aclCacheRefreshSecond` | int | `60` | ACL cache refresh time (seconds) |
+| `statefulAuthenticationCacheMaxNum` | int | `10000` | Maximum stateful
authentication cache size |
+| `statefulAuthenticationCacheExpiredSecond` | int | `60` | Stateful
authentication cache expiration time (seconds) |
+| `statefulAuthorizationCacheMaxNum` | int | `10000` | Maximum stateful
authorization cache size |
+| `statefulAuthorizationCacheExpiredSecond` | int | `60` | Stateful
authorization cache expiration time (seconds) |
+
+### Authentication and Authorization Strategies
+
+#### Stateless Strategy - Default
+
+- **Characteristics**: Performs complete authentication and authorization
check for every request
+- **Advantages**: High security, permission changes take effect immediately
+- **Disadvantages**: Higher performance overhead
+- **Use Cases**: Environments with extremely high security requirements
+- **Default**: ✅ System uses this strategy by default
+
+**Configuration Example**:
+
+```properties
+# Default values, can be omitted
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatelessAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatelessAuthorizationStrategy
+```
+
+#### Stateful Strategy - Recommended for Production
+
+- **Characteristics**: First request performs authentication/authorization,
subsequent requests use cached results
+- **Advantages**: Lower performance overhead, higher throughput
+- **Disadvantages**: Permission changes have delay (takes effect after cache
expires)
+- **Use Cases**: High throughput scenarios, recommended for production
environments
+- **Recommendation**: ⭐ Explicitly configure this strategy for production
environments
+
+**Configuration Example**:
+
+```properties
+# Recommended for production
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+```
+
+---
+
+## User Management
+
+### User Type Description
+
+| User Type | Description | Permission Scope | Use Case |
+|-----------|-------------|------------------|----------|
+| **Super** | Super user | Has all permissions on all resources, no separate
authorization needed | System administrator, operations personnel |
+| **Normal** | Normal user | Requires explicit authorization to access
resources | Business applications, services |
+
+### mqadmin Tool Configuration
+
+Before using the mqadmin command-line tool, configure admin credentials.
+
+**Configuration File**: `conf/tools.yml`
+
+```yaml
+# Use super user's username and password
+accessKey: rocketmq
+secretKey: 12345678
+```
+
+**Verify Configuration**:
+
+```bash
+# Test if mqadmin tool can connect normally
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+```
+
+### User Management Commands
+
+#### Create User
+
+```bash
+# Create normal user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
password -t Normal
+
+# Create super user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster -u rocketmq -p
12345678 -t Super
+```
+
+#### Update User
+
+```bash
+# Update user password
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
newpassword
+
+# Update user type
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -t
Super
+```
+
+#### Query User
+
+```bash
+# Query user details
+sh bin/mqadmin getUser -n 127.0.0.1:9876 -c DefaultCluster -u username
+
+# Query user list
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+
+# Query user list with filter
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster -f producer
+```
+
+#### Delete User
+
+```bash
+sh bin/mqadmin deleteUser -n 127.0.0.1:9876 -c DefaultCluster -u username
+```
+
+### Command Parameters
+
+| Parameter | Required | Description | Default |
+|-----------|----------|-------------|---------|
+| `-n` | Yes | NameServer address | - |
+| `-c` | No | Cluster name (choose one with `-b`) | - |
+| `-b` | No | Broker address (choose one with `-c`) | - |
+| `-u` | Yes | Username | - |
+| `-p` | No | Password (used for create/update) | - |
+| `-t` | No | User type: Super or Normal | Normal |
+| `-f` | No | Filter condition (used for query) | - |
+
+---
+
+## Permission Management
+
+### Core Concepts
+
+#### Resource Types
+
+| Resource Type | Format | Example | Description |
+|---------------|--------|---------|-------------|
+| **Any** | `*` | `*` | All resources |
+| **Cluster** | `Cluster:cluster_name` | `Cluster:DefaultCluster` |
Cluster-level resource |
+| **Namespace** | `Namespace:namespace` | `Namespace:test` | Namespace |
+| **Topic** | `Topic:topic_name` | `Topic:TestTopic` | Message topic |
+| **Group** | `Group:group_name` | `Group:TestGroup` | Consumer group |
+
+#### Resource Matching Modes
+
+| Matching Mode | Description | Example | Match Result |
+|---------------|-------------|---------|--------------|
+| **Exact Match (LITERAL)** | Exact resource name match | `Topic:OrderTopic` |
Matches only `Topic:OrderTopic` |
+| **Prefix Match (PREFIXED)** | Matches resources with specified prefix |
`Topic:Order*` | Matches `Topic:OrderTopic`, `Topic:OrderDLQTopic`, etc. |
+| **Wildcard Match (ANY)** | Matches all resources of the type | `Topic:*` |
Matches all Topics |
+
+#### Action Types
+
+| Action | Description | Applicable Resources |
+|--------|-------------|---------------------|
+| **Pub** | Publish messages | Topic |
+| **Sub** | Subscribe messages | Topic, Group |
+| **Create** | Create resource | Cluster, Namespace, Topic, Group |
+| **Update** | Update resource | Cluster, Namespace, Topic, Group |
+| **Delete** | Delete resource | Cluster, Namespace, Topic, Group |
+| **Get** | Query resource details | Cluster, Namespace, Topic, Group |
+| **List** | Query resource list | Cluster, Namespace, Topic, Group |
+| **All** | All operations | All resources |
+
+#### Decision Types
+
+| Decision | Description |
+|----------|-------------|
+| **Allow** | Allow operation |
+| **Deny** | Deny operation (higher priority than Allow) |
+
+
+### Permission Priority Rules
+
+When multiple permission policies match the same request, the final result is
determined by the following priority.
+
+#### Priority Rules
+
+|| Resource Priority (High→Low) | Decision Priority |
+||------------------------------|------------------|
+|| 1. Specific resource type > Any resource type (`*`)<br/>2. Exact match >
Prefix match > Wildcard match<br/>3. Longer resource name > Shorter resource
name | **Deny > Allow**<br/>(Deny has higher priority than Allow) |
+
+#### Priority Example
+
+|| Policy | Resource Definition | Action | Decision | Priority |
+||--------|-------------------|--------|----------|----------|
+|| 1 | `Topic:test-abc-1` | Pub,Sub | Deny | Highest |
+|| 2 | `Topic:test-abc` | Pub,Sub | Allow | High |
+|| 3 | `Topic:test-*` | Pub,Sub | Allow | Medium |
+|| 4 | `Topic:*` | Pub,Sub | Allow | Low |
+|| 5 | `*` | All | Deny | Lowest |
+
+**Match Results**:
+
+|| Access Resource | Matched Policy | Final Decision |
+||----------------|----------------|----------------|
+|| `Topic:test-abc-1` | Policy 1 (exact match) | ❌ Deny |
+|| `Topic:test-abc` | Policy 2 (exact match) | ✅ Allow |
+|| `Topic:test-123` | Policy 3 (prefix match) | ✅ Allow |
+|| `Topic:other` | Policy 4 (wildcard match) | ✅ Allow |
+|| `Group:TestGroup` | Policy 5 (any resource) | ❌ Deny |
+
+### Permission Management Commands
+
+#### Create Permission
+
+**Basic Usage Examples**:
+
+```bash
+# Example 1: Grant publish permission for a single Topic
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -d Allow
+
+# Example 2: Grant subscribe permission for a single Topic (need to specify
both Topic and Group)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:consumer_user -r Topic:TestTopic,Group:TestGroup -a Sub -d Allow
+
+# Example 3: Grant multiple operation permissions
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user -r Topic:TestTopic -a Create,Update,Delete,Get,List -d
Allow
+```
+
+**Resource Matching Mode Examples**:
+
+```bash
+# Example 4: Exact match - precise resource name match
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:OrderTopic -a Pub,Sub -d Allow
+
+# Example 5: Prefix match - matches all Topics starting with order_
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:order_* -a Pub -d Allow
+
+# Example 6: Wildcard match - matches all Topics
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:monitor_user -r Topic:* -a Get,List -d Allow
+
+# Example 7: Match all resource types
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:super_admin -r * -a All -d Allow
+```
+
+**IP Whitelist Examples**:
+
+```bash
+# Example 8: Restrict single IP access
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -i 192.168.1.100 -d Allow
+
+# Example 9: Restrict IP range access (CIDR format)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:internal_user -r Topic:InternalTopic -a Pub,Sub -i 192.168.1.0/24 -d
Allow
+
+# Example 10: No IP restriction (do not specify -i parameter)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:public_user -r Topic:PublicTopic -a Pub -d Allow
+```
+
+**Deny Policy Examples**:
+
+```bash
+# Example 11: Deny access to sensitive Topic
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:SensitiveTopic -a Pub,Sub -d Deny
+
+# Example 12: Grant most permissions first, then deny specific resources (Deny
has higher priority)
+# Step 1: Grant access to all Topics
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:* -a Pub,Sub -d Allow
+# Step 2: Deny sensitive Topic (overrides above Allow)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:SensitiveTopic -a Pub,Sub -d Deny
+```
+
+**Cluster Management Permission Examples**:
+
+```bash
+# Example 13: Grant cluster query permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:monitor_user -r Cluster:DefaultCluster -a Get,List -d Allow
+
+# Example 14: Grant Topic management permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:topic_admin -r Topic:* -a Create,Update,Delete,Get,List -d Allow
+
+# Example 15: Grant Group management permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:group_admin -r Group:* -a Create,Update,Delete,Get,List -d Allow
+```
+
+#### Update Permission
+
+```bash
+sh bin/mqadmin updateAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub,Sub -d Allow
+```
+
+#### Query Permission
+
+```bash
+# Query all permissions of a user
+sh bin/mqadmin getAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:producer_user
+
+# Query all permission list
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster
+
+# Query permission list with filter
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user -r Topic:TestTopic
+```
+
+#### Delete Permission
+
+```bash
+# Delete all permissions of a user
+sh bin/mqadmin deleteAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user
+
+# Delete user's permission for specific resource
+sh bin/mqadmin deleteAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user -r Topic:TestTopic
+```
+
+### Command Parameters
+
+| Parameter | Required | Description | Example |
+|-----------|----------|-------------|---------|
+| `-n` | Yes | NameServer address | `127.0.0.1:9876` |
+| `-c` | No | Cluster name (choose one with `-b`) | `DefaultCluster` |
+| `-b` | No | Broker address (choose one with `-c`) | `192.168.1.1:10911` |
+| `-s` | Yes | Subject name | `User:producer_user` |
+| `-r` | No | Resource definition (comma-separated) |
`Topic:TestTopic`<br/>`Topic:*`<br/>`Topic:Order*,Group:Order*` |
+| `-a` | No | Action type (comma-separated) |
`Pub`<br/>`Pub,Sub`<br/>`Create,Update,Delete` |
+| `-i` | No | IP whitelist (supports IP or IP range) |
`192.168.1.100`<br/>`192.168.1.0/24` |
+| `-d` | No | Decision result | `Allow` or `Deny` |
+
-### 2.1 Permission definition
+---
-The definition of access access control for RocketMQ Topic resources is mainly
as shown in the following table, divided into the following four categories:
+## Client Usage
-| Permission | Definition |
-| ---------- | --------------------- |
-| DENY | reject |
-| ANY | PUB or SUB permission |
-| PUB | send permission |
-| SUB | subscribe permission |
+### Java Client Configuration
-### 2.2 Key attributes of permission definitions
+#### Maven Dependency
-| Field | Value | Definition
|
-| -------------------------- | ---------------------------- |
-------------------------------------- |
-| globalWhiteRemoteAddresses | \*;192.168.\*.\*;192.168.0.1 | Global IP
whitelist |
-| accessKey | string | Access Key
|
-| secretKey | string | Secret Key
|
-| whiteRemoteAddress | \*;192.168.\*.\*;192.168.0.1 | User IP
whitelist |
-| admin | true;false | Whether it is an
administrator account |
-| defaultTopicPerm | DENY;PUB;SUB;PUB\|SUB | default Topic
permission |
-| defaultGroupPerm | DENY;PUB;SUB;PUB\|SUB | defalutl
ConsumerGroup permission |
-| topicPerms | topic=permission | Permissions for
each Topic |
-| groupPerms | group=permission | Permissions for
each Consumer Group |
+```xml
+<dependency>
+ <groupId>org.apache.rocketmq</groupId>
+ <artifactId>rocketmq-client-java</artifactId>
+ <version>5.3.4</version>
+</dependency>
+```
+
+### Message Producer
+
+```java
+import org.apache.rocketmq.client.apis.ClientConfiguration;
+import org.apache.rocketmq.client.apis.ClientServiceProvider;
+import org.apache.rocketmq.client.apis.SessionCredentials;
+import org.apache.rocketmq.client.apis.StaticSessionCredentialsProvider;
+import org.apache.rocketmq.client.apis.producer.Producer;
+import org.apache.rocketmq.client.apis.message.Message;
+
+public class ProducerWithACL {
+ public static void main(String[] args) throws Exception {
+ // 1. Create credentials provider
+ SessionCredentials credentials = new SessionCredentials(
+ "producer_user", // AccessKey (username)
+ "producer123" // SecretKey (password)
+ );
+ StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ // 2. Configure client
+ ClientConfiguration clientConfiguration =
ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:8081") // Proxy or Broker address
+ .setCredentialProvider(credentialsProvider)
+ .build();
+
+ // 3. Create producer
+ ClientServiceProvider provider = ClientServiceProvider.loadService();
+ Producer producer = provider.newProducerBuilder()
+ .setClientConfiguration(clientConfiguration)
+ .setTopics("TestTopic")
+ .build();
+
+ // 4. Send message
+ Message message = provider.newMessageBuilder()
+ .setTopic("TestTopic")
+ .setBody("Hello RocketMQ with ACL".getBytes())
+ .build();
+
+ producer.send(message);
+ System.out.println("Message sent successfully");
+
+ // 5. Close producer
+ producer.close();
+ }
+}
+```
+
+### Message Consumer
+
+```java
+import org.apache.rocketmq.client.apis.ClientConfiguration;
+import org.apache.rocketmq.client.apis.ClientServiceProvider;
+import org.apache.rocketmq.client.apis.SessionCredentials;
+import org.apache.rocketmq.client.apis.StaticSessionCredentialsProvider;
+import org.apache.rocketmq.client.apis.consumer.PushConsumer;
+import org.apache.rocketmq.client.apis.consumer.FilterExpression;
+import org.apache.rocketmq.client.apis.consumer.FilterExpressionType;
+import org.apache.rocketmq.client.apis.consumer.ConsumeResult;
+
+import java.util.Collections;
+
+public class ConsumerWithACL {
+ public static void main(String[] args) throws Exception {
+ // 1. Create credentials provider
+ SessionCredentials credentials = new SessionCredentials(
+ "consumer_user", // AccessKey (username)
+ "consumer123" // SecretKey (password)
+ );
+ StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ // 2. Configure client
+ ClientConfiguration clientConfiguration =
ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:8081")
+ .setCredentialProvider(credentialsProvider)
+ .build();
+
+ // 3. Create consumer
+ ClientServiceProvider provider = ClientServiceProvider.loadService();
+ FilterExpression filterExpression = new FilterExpression("*",
FilterExpressionType.TAG);
+
+ PushConsumer consumer = provider.newPushConsumerBuilder()
+ .setClientConfiguration(clientConfiguration)
+ .setConsumerGroup("TestGroup")
+ .setSubscriptionExpressions(Collections.singletonMap("TestTopic",
filterExpression))
+ .setMessageListener(messageView -> {
+ System.out.println("Received message: " + new
String(messageView.getBody().array()));
+ return ConsumeResult.SUCCESS;
+ })
+ .build();
+
+ System.out.println("Consumer started successfully");
+
+ // Keep running
+ Thread.sleep(Long.MAX_VALUE);
+ }
+}
+```
+
+### Spring Boot Integration
+
+```yaml
+# application.yml
+rocketmq:
+ name-server: 127.0.0.1:9876
+ producer:
+ group: producer-group
+ access-key: producer_user
+ secret-key: producer123
+ consumer:
+ group: consumer-group
+ access-key: consumer_user
+ secret-key: consumer123
+ topics:
+ - TestTopic
+```
+
+---
-Refer to the **distribution/conf/plain_acl.yml** configuration file for
specific information.
+## Common Scenarios
-## 3. Deployment of clusters supporting access control
+### Scenario 1: Separate Producer and Consumer
-After defining the permission attributes in the
**distribution/conf/plain_acl.yml** configuration file as described above, you
can turn on the ACL feature of the RocketMQ cluster by turning on the
**aclEnable** switch variable. Here is the properties configuration file
content for enabling the ACL feature on the Broker：
+**Requirement**: Producer can only send messages, consumer can only consume
messages
+```bash
+# Create producer user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u producer_user -p producer123 -t Normal
+
+# Create consumer user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u consumer_user -p consumer123 -t Normal
+
+# Grant producer publish permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -d Allow
+
+# Grant consumer subscribe permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:consumer_user -r Topic:TestTopic,Group:TestGroup -a Sub -d Allow
```
-brokerClusterName=DefaultCluster
-brokerName=broker-a
-brokerId=0
-deleteWhen=04
-fileReservedTime=48
-brokerRole=ASYNC_MASTER
-flushDiskType=ASYNC_FLUSH
-storePathRootDir=/data/rocketmq/rootdir-a-m
-storePathCommitLog=/data/rocketmq/commitlog-a-m
-autoCreateSubscriptionGroup=true
-## if acl is open,the flag will be true
-aclEnable=true
-listenPort=10911
-brokerIP1=XX.XX.XX.XX1
-namesrvAddr=XX.XX.XX.XX:9876
+
+### Scenario 2: Permissions by Business Module
+
+**Requirement**: Different business modules use different Topic prefixes, each
module can only access its own Topics
+
+```bash
+# Create order module user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u order_service -p order123 -t Normal
+
+# Grant order module permission (can access all Topics starting with order_)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:order_* -a Pub,Sub -d Allow
+
+# Create payment module user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u payment_service -p payment123 -t Normal
+
+# Grant payment module permission (can access all Topics starting with
payment_)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:payment_service -r Topic:payment_* -a Pub,Sub -d Allow
```
-## 4. Main process of access control
+### Scenario 3: IP Whitelist Restriction
-The main process of ACL is divided into two parts, mainly including permission
parsing and permission verification.
+**Requirement**: Only allow specific IP ranges to access
-### 4.1 Permission parsing
+```bash
+# Create user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u internal_user -p internal123 -t Normal
-The Broker parses the client's RequestCommand request and gets the attributes
fields that need to be authenticated, mainly including:
+# Grant permission but restrict to internal IP access only
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:internal_user \
+ -r Topic:InternalTopic \
+ -a Pub,Sub \
+ -i 192.168.1.0/24,10.0.0.0/8 \
+ -d Allow
+```
+
+### Scenario 4: Administrator Permission
-1. AccessKey: Similar to a username, it refers to the user subject and
corresponds to the permission data.
-2. Signature: A string obtained by the client signing with the SecretKey,
which the server then verifies with the SecretKey.
+**Requirement**: Administrator needs to manage Topic and Group creation,
update, deletion
-### 4.2 Permission verification
+```bash
+# Create admin user
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u admin_user -p admin_user123 -t Normal
-The permission verification logic on the Broker side is mainly divided into
the following steps:
+# Grant cluster management permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Cluster:DefaultCluster \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
-1. Check if it hits the global IP whitelist; if it is, it is considered to
have passed the verification; otherwise, go to 2.
-2. Check if it hits the user IP whitelist; if it is, it is considered to have
passed the verification; otherwise, go to 3.
-3. Verify the signature, if the verification fails, throw an exception; if it
passes, go to 4.
-4. Verify the permissions required by the user request against the permissions
owned by the user; if it fails, throw an exception.
+# Grant all Topic management permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Topic:* \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
-The verification of the required permissions for the user needs to pay
attention to the following content:
+# Grant all Group management permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Group:* \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
+```
-1. Special requests such as UPDATE_AND_CREATE_TOPIC can only be operated by
the admin account.
-2. For a certain resource, if there is an explicit configuration permission,
the configured permission is used; if there is no explicit configuration
permission, the default permission is used.
+### Scenario 5: Deny Access to Sensitive Topic
-## 5. Hot reload modified access control definitions
+**Requirement**: Explicitly deny certain users from accessing sensitive Topics
-The default implementation of RocketMQ's access control storage is based on
the yml configuration file. Users can dynamically modify the properties of the
access control definition without restarting the Broker service node.
+```bash
+# Grant user access to most Topics
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user \
+ -r Topic:* \
+ -a Pub,Sub \
+ -d Allow
-## 6. Usage limits for access control
+# Deny access to sensitive Topic (Deny has higher priority than Allow)
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user \
+ -r Topic:SensitiveTopic \
+ -a Pub,Sub \
+ -d Deny
+```
-1. If ACL is enabled together with high availability deployment (Master/Slave
architecture), you need to set the global whitelist information in the
distribution/conf/plain_acl.yml configuration file on the Broker Master node,
that is, set the IP address of the Slave node to the global whitelist in the
plain_acl.yml configuration file on the Master node.
-2. If ACL is enabled together with high availability deployment (multi-replica
Dledger architecture), because the primary node will be automatically selected
in the Dledger Group when a node goes down, you need to set the whitelist in
the plain_acl.yml configuration file of all Broker nodes in the Dledger Group
to the IP address of all Broker nodes.
+---
-## 7. ACL mqadmin configuration management commands
+## Troubleshooting
-### 7.1 Update the value of the "account" attribute in the ACL configuration
file
+### Common Errors
-An example of this command is as follows：
+#### 1. mqadmin Tool Command Execution Failed
-```shell
-$ sh mqadmin updateAclConfig -n 192.168.1.2:9876 -b 192.168.12.134:10911 -a
RocketMQ -s 1234567809123 -t topicA=DENY,topicD=SUB -g groupD=DENY,groupB=SUB
+**Error Message**:
```
+CODE: 17 DESC: No user
+or
+CODE: 16 DESC: Authentication failed
+```
+
+**Possible Causes**:
+- `conf/tools.yml` file not configured
+- Credentials in `tools.yml` are incorrect
+- Configured user is not a super user
-Explain: If it does not exist, it will be created in the ACL Config YAML
configuration file; if it exists, it will update the corresponding "accounts"
attribute; if the specified cluster name is specified, the command will be
executed on each broker node in the cluster; otherwise, the command will be
executed on a single broker node.
+**Solution**:
+```bash
+# 1. Check if tools.yml file exists
+ls conf/tools.yml
-| Parameter | Value | Definition
|
-| --------- | ------------------------- |
------------------------------------------------------------ |
-| n | eg:192.168.1.2:9876 | Namesrv address (required)
|
-| c | eg:DefaultCluster | Specify cluster name(Choose one with
the broker address) |
-| b | eg:192.168.12.134:10911 | Specify broker address(Choose one
with the cluster name) |
-| a | eg:RocketMQ | Access Key value(required)
|
-| s | eg:1234567809123 | Secret Key value(optional)
|
-| m | eg:true | Whether it is an administrator
account (optional) |
-| w | eg:192.168.0.* | whiteRemoteAddress,user IP whitelist
(optional) |
-| i | eg:DENY;PUB;SUB;PUB\|SUB | defaultTopicPerm,default Topic
permissions (optional) |
-| u | eg:DENY;PUB;SUB;PUB\|SUB | defaultGroupPerm,default Consumer
Group permissions (optional) |
-| t | eg:topicA=DENY,topicD=SUB | topicPerms,permissions for each
Topic (optional) |
-| g | eg:groupD=DENY,groupB=SUB | groupPerms,permissions for each
Consumer Group (optional) |
+# 2. Configure admin credentials
+cat > conf/tools.yml << EOF
+accessKey: rocketmq
+secretKey: 12345678
+EOF
-### 7.2 Delete the corresponding "account" in the ACL configuration file
+# 3. Verify configuration
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+```
-An example of this command is as follows：
+#### 2. Client Authentication Failed
-```shell
-$ sh mqadmin deleteAccessConfig -n 192.168.1.2:9876 -c DefaultCluster -a
RocketMQ
+**Error Message**:
+```
+[AUTHENTICATION] User:xxx is authenticated failed with Signature = xxx
```
-Explain: If the specified cluster name is specified, the command will be
executed on each broker node in the cluster; otherwise, the command will be
executed on a single broker node. The parameter "a" is the value of the Access
Key, which is used to identify the unique account ID, so the account ID can be
specified in the command parameter.
+**Possible Causes**:
+- Incorrect username or password
+- User does not exist
+- User is disabled
-| Parameter | Value | Definition
|
-| --------- | ----------------------- |
-------------------------------------------------------- |
-| n | eg:192.168.1.2:9876 | namesrv address(required)
|
-| c | eg:DefaultCluster | Specify cluster name(Choose one with
the broker address) |
-| b | eg:192.168.12.134:10911 | Specify broker address(Choose one with
the cluster name) |
-| a | eg:RocketMQ | Access Key value(required)
|
+**Troubleshooting Steps**:
+```bash
+# 1. Check if user exists
+sh bin/mqadmin getUser -n 127.0.0.1:9876 -c DefaultCluster -u username
+# 2. Verify client configuration has correct username and password
-### 7.3 Update the global whitelist in the ACL configuration file
+# 3. Reset user password
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
newpassword
+```
-An example of this command is as follows：
+#### 3. Authorization Failed
-```shell
-sh mqadmin updateGlobalWhiteAddr -n 192.168.1.2:9876 -b 192.168.12.134:10911
-g 10.10.154.1,10.10.154.2
+**Error Message**:
```
+[AUTHORIZATION] Subject = User:xxx is Deny Action = Pub from sourceIp = xxx on
resource = Topic:xxx
+```
+
+**Possible Causes**:
+- User does not have permission for the resource
+- IP not in whitelist
+- Deny rule exists
-Explain: If the specified cluster name is specified, the command will be
executed on each broker node in the cluster; otherwise, the command will be
executed on a single broker node. The parameter "g" is the value of the global
IP whitelist, which is used to update the "globalWhiteRemoteAddresses" field
attribute value in the ACL configuration file.
+**Troubleshooting Steps**:
+```bash
+# 1. Check user's permission configuration
+sh bin/mqadmin getAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:username
-| Parameter | Value | Definition
|
-| --------- | -------------------------- |
-------------------------------------------------------- |
-| n | eg:192.168.1.2:9876 | namesrv address(required)
|
-| c | eg:DefaultCluster | Specify cluster name(Choose one
with the broker address) |
-| b | eg:192.168.12.134:10911 | Specify broker address(Choose one
with the cluster name) |
-| g | eg:10.10.154.1,10.10.154.2 | Global IP whitelist(required)
|
+# 2. Check if Deny rules exist
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:username
-### 7.4 Query the ACL configuration file version information of the cluster
Broker
+# 3. Grant appropriate permission
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:username -r Topic:TestTopic -a Pub -d Allow
+```
-An example of this command is as follows：
+#### 4. Inter-component Communication Failed
-```shell
-sh mqadmin clusterAclConfigVersion -n 192.168.1.2:9876 -c DefaultCluster
+**Error Message**:
+```
+Slave Broker connect to Master failed
+or
+Proxy connect to Broker failed
```
-Explain: If the specified cluster name is specified, the command will be
executed on each broker node in the cluster; otherwise, the command will be
executed on a single broker node.
+**Possible Causes**:
+- `innerClientAuthenticationCredentials` misconfigured
+- Inconsistent authentication credentials between components
+- Master/Slave credential configuration mismatch
+
+**Solution**:
+```bash
+# Check if all component configurations are consistent
+grep "innerClientAuthenticationCredentials" conf/*.conf conf/*.json
+
+# Modify to unified credentials
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+### View Audit Logs
+
+All authentication and authorization operations are logged in Broker/Proxy
logs.
+
+**View Authentication Logs**:
+```bash
+grep "AUTHENTICATION" logs/rocketmqlogs/broker.log
+
+# Authentication success example
+# [AUTHENTICATION] User:producer_user is authenticated success with Signature
= xxx
+
+# Authentication failure example
+# [AUTHENTICATION] User:producer_user is authenticated failed with Signature =
xxx
+```
+
+**View Authorization Logs**:
+```bash
+grep "AUTHORIZATION" logs/rocketmqlogs/broker.log
+
+# Authorization success example
+# [AUTHORIZATION] Subject = User:producer_user is Allow Action = Pub from
sourceIp = 192.168.1.100 on resource = Topic:TestTopic
+
+# Authorization failure example
+# [AUTHORIZATION] Subject = User:producer_user is Deny Action = Sub from
sourceIp = 192.168.1.100 on resource = Topic:TestTopic
+```
+
+---
+
+## Best Practices
+
+### 1. User Management
+
+✅ **Recommended Practices**:
+- Create independent users for different applications or services
+- Use strong passwords (at least 8 characters, including letters and numbers)
+- Super users should only be used for system initialization and emergency
operations
+- Avoid using weak passwords (e.g., 123456)
+
+❌ **Avoid**:
+- Multiple applications sharing the same user
+- Using weak passwords (e.g., 123456)
+- Excessive use of super users in production
+
+### 2. Permission Configuration
+
+✅ **Recommended Practices**:
+- Follow the principle of least privilege, grant only necessary permissions
+- Use prefix matching to simplify permission management for similar resources
+- Use Deny rules to protect sensitive resources
+- Producers should only be granted Pub permission, consumers should only be
granted Sub permission
+
+❌ **Avoid**:
+- Granting all users All permission on `*` resource
+- Excessive use of wildcard matching
+- Ignoring IP whitelist configuration
+
+### 3. Strategy Selection
+
+**Choose Stateless Strategy for**:
+- Finance, payment, and other scenarios with extremely high security
requirements
+- Scenarios where permission changes need to take effect immediately
+- Low throughput scenarios
+
+**Choose Stateful Strategy for**:
+- E-commerce, logging, and other high throughput scenarios
+- Scenarios where permission changes are infrequent
+- Scenarios with high performance requirements
+
+### 4. Production Environment Deployment Tuning
+
+For production deployment, in addition to basic configuration (refer to [Quick
Start](#quick-start)), pay attention to the following parameter tuning.
+
+#### Integrated Storage-Compute Architecture Tuning
+
+```properties
+# broker.conf
+# Basic configuration
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+
+# Production performance tuning: use stateful strategy (default is stateless)
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+
+# Cache configuration (adjust based on number of users and QPS)
+userCacheMaxNum = 5000
+userCacheExpiredSecond = 3600
+userCacheRefreshSecond = 300
+aclCacheMaxNum = 5000
+aclCacheExpiredSecond = 3600
+aclCacheRefreshSecond = 300
+statefulAuthenticationCacheMaxNum = 20000
+statefulAuthenticationCacheExpiredSecond = 60
+statefulAuthorizationCacheMaxNum = 20000
+statefulAuthorizationCacheExpiredSecond = 60
+```
+
+#### Separated Storage-Compute Architecture Tuning (Recommended)
+
+**Broker Configuration** (`broker.conf`):
+
+```properties
+# Broker only acts as metadata provider
+authenticationEnabled = false
+authorizationEnabled = false
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+**Proxy Configuration** (`rmq-proxy.json`):
+
+```json
+{
+ "authenticationEnabled": true,
+ "authenticationProvider":
"org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider",
+ "authenticationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthenticationMetadataProvider",
+ "authenticationStrategy":
"org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy",
+ "innerClientAuthenticationCredentials": "{\"accessKey\":\"rocketmq\",
\"secretKey\":\"12345678\"}",
+
+ "authorizationEnabled": true,
+ "authorizationProvider":
"org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider",
+ "authorizationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthorizationMetadataProvider",
+ "authorizationStrategy":
"org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy",
+
+ "userCacheMaxNum": 5000,
+ "userCacheExpiredSecond": 3600,
+ "userCacheRefreshSecond": 300,
+ "aclCacheMaxNum": 5000,
+ "aclCacheExpiredSecond": 3600,
+ "aclCacheRefreshSecond": 300,
+ "statefulAuthenticationCacheMaxNum": 20000,
+ "statefulAuthenticationCacheExpiredSecond": 60,
+ "statefulAuthorizationCacheMaxNum": 20000,
+ "statefulAuthorizationCacheExpiredSecond": 60
+}
+```
+
+**Tuning Recommendations**:
+
+| Parameter | Recommended Value | Description |
+|-----------|------------------|-------------|
+| `userCacheMaxNum` | Number of users × 1.5 | Avoid frequent loading of user
data |
+| `aclCacheMaxNum` | Number of users × 1.5 | Avoid frequent loading of
permission data |
+| `statefulAuthenticationCacheMaxNum` | Number of connections × 2 | Cache
authentication result for each connection |
+| `statefulAuthorizationCacheMaxNum` | Number of connections × resources × 2 |
Cache authorization result for each connection on each resource |
+
+### 5. Migrating from ACL 1.0 to ACL 2.0
+
+**Migration Steps**:
+
+```bash
+# 1. Backup ACL 1.0 configuration
+cp conf/plain_acl.yml conf/plain_acl.yml.backup
+
+# 2. Enable migration in Broker configuration
+echo "migrateAuthFromV1Enabled = true" >> conf/broker.conf
+
+# 3. Enable ACL 2.0
+cat >> conf/broker.conf << EOF
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+EOF
+
+# 4. Restart Broker (migration will execute automatically on startup)
+sh bin/mqbroker -n localhost:9876 -c conf/broker.conf
+
+# 5. Verify migration results
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster
+
+# 6. After successful migration, disable migration switch
+# migrateAuthFromV1Enabled = false
+
+# 7. Delete old configuration file (optional)
+rm conf/plain_acl.yml
+```
+
+**Notes**:
+- ACL 1.0 IP whitelist will not be migrated (behavior inconsistency)
+- Existing users and permissions will not be overwritten
+- It is recommended to verify migration results in test environment first
+- After successful migration, it is recommended to delete `plain_acl.yml` file
to avoid confusion
+
+### 6. Expanding New Broker
+
+When expanding the cluster with new Brokers, you need to synchronize user and
permission data.
+
+**Copy all users from old Broker to new Broker**:
+
+```bash
+# Copy all users
+sh bin/mqadmin copyUser -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911
+
+# Copy all permissions
+sh bin/mqadmin copyAcl -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911
+```
+
+**Copy specific user from old Broker to new Broker**:
+
+```bash
+# Copy specific user
+sh bin/mqadmin copyUser -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911 -u producer_user
+
+# Copy permissions for this user
+sh bin/mqadmin copyAcl -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911 -s User:producer_user
+```
+
+### 7. Monitoring and Alerting
+
+**Recommended Monitoring Metrics**:
+- Authentication failure count
+- Authorization denial count
+- Cache hit rate
+- User count
+- ACL rule count
+
+**Log Monitoring Script Example**:
+```bash
+#!/bin/bash
+# Monitor authentication failure count
+auth_fail_count=$(grep "authenticated failed" logs/rocketmqlogs/broker.log |
wc -l)
+if [ $auth_fail_count -gt 100 ]; then
+ echo "Alert: Too many authentication failures: $auth_fail_count"
+fi
+
+# Monitor authorization denial count
+authz_deny_count=$(grep "is Deny" logs/rocketmqlogs/broker.log | wc -l)
+if [ $authz_deny_count -gt 100 ]; then
+ echo "Alert: Too many authorization denials: $authz_deny_count"
+fi
+```
+
+---
+
+## Appendix
+
+### Complete Configuration Example
+
+#### Broker Production Environment Configuration
+
+```properties
+# broker.conf
-| Parameter | Value | Definition
|
-| --------- | ----------------------- |
-------------------------------------------------------- |
-| n | eg:192.168.1.2:9876 | namesrv address(required)
|
-| c | eg:DefaultCluster | Specify cluster name(Choose one with
the broker address) |
-| b | eg:192.168.12.134:10911 | Specify broker address(Choose one with
the cluster name) |
+# Basic configuration
+brokerClusterName = DefaultCluster
+brokerName = broker-a
+brokerId = 0
+deleteWhen = 04
+fileReservedTime = 48
+brokerRole = ASYNC_MASTER
+flushDiskType = ASYNC_FLUSH
-### 7.5 Query the entire contents of the ACL configuration file of the cluster
Broker
+# ACL authentication configuration
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
-An example of this command is as follows：
+# ACL authorization configuration
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
-```shell
-sh mqadmin getAccessConfigSubCommand -n 192.168.1.2:9876 -c DefaultCluster
+# Cache configuration
+userCacheMaxNum = 5000
+userCacheExpiredSecond = 3600
+userCacheRefreshSecond = 300
+aclCacheMaxNum = 5000
+aclCacheExpiredSecond = 3600
+aclCacheRefreshSecond = 300
+statefulAuthenticationCacheMaxNum = 10000
+statefulAuthenticationCacheExpiredSecond = 60
+statefulAuthorizationCacheMaxNum = 10000
+statefulAuthorizationCacheExpiredSecond = 60
```
-Explain: If the specified cluster name is specified, the command will be
executed on each broker node in the cluster; Otherwise, the command is executed
on a single broker node.
+---
-| Parameter | Value | Definition
|
-| --------- | ----------------------- |
-------------------------------------------------------- |
-| n | eg:192.168.1.2:9876 | namesrv address(required)
|
-| c | eg:DefaultCluster | Specify cluster name(Choose one with
the broker address) |
-| b | eg:192.168.12.134:10911 | Specify broker address(Choose one with
the cluster name) |
+**Document Version**: 1.0
+**Applicable RocketMQ Version**: 5.3.0+
+**Last Updated**: November 2024
-**Special attention**: The problem of abnormal data synchronization of Broker
under Master/Slave and Dledger modes after Acl authentication is enabled has
been fixed in the [4.5.1] version of the community. The specific PR link is:
https://github.com/apache/rocketmq/pull/1149
\ No newline at end of file
diff --git
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/07access-1.0.md
similarity index 96%
copy from
i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
copy to
i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/07access-1.0.md
index e580147747..e9ff10d2b6 100644
---
a/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/03access.md
+++
b/i18n/en/docusaurus-plugin-content-docs/version-5.0/06-bestPractice/07access-1.0.md
@@ -1,4 +1,18 @@
-# Access Control
+---
+unlisted: true
+---
+
+# Access Control (ACL 1.0)
+
+:::warning Legacy Documentation
+
+This document describes **RocketMQ ACL 1.0**, applicable to **RocketMQ 4.x,
5.0-5.2, and 5.3.0-5.3.2**.
+
+**Starting from RocketMQ 5.3.3, ACL 1.0 has been removed and is no longer
supported.**
+
+If you are using **RocketMQ 5.3.0** or above, it is strongly recommended to
use [ACL 2.0 Documentation](03access.md), which provides more powerful and
flexible access control features.
+
+:::
## 1. Introduction to access control features
diff --git a/versioned_docs/version-5.0/06-bestPractice/03access.md
b/versioned_docs/version-5.0/06-bestPractice/03access.md
index fb15354045..3a0c51539f 100644
--- a/versioned_docs/version-5.0/06-bestPractice/03access.md
+++ b/versioned_docs/version-5.0/06-bestPractice/03access.md
@@ -1,179 +1,1180 @@
-# 权限控制
+# RocketMQ ACL 2.0 使用手册
-## 1.权限控制特性介绍
-权限控制（ACL）主要为 RocketMQ 提供 Topic
资源级别的高级访问控制功能。用户在使用RocketMQ权限控制时，可以在Client客户端注入用户名和密码参数实现签名，服务端通过权限控制参数实现各个资源的权限管理和校验。
+:::info 版本说明
-:::info
-ACL控制在增强集群访问控制安全性的同时也会带来部署流程和运维管理的复杂度。
+本文档介绍的是 **RocketMQ ACL 2.0**，适用于 **RocketMQ 5.3.0** 及以上版本。
+
+- 如果您使用的是 **RocketMQ 4.x、5.0-5.2 或 5.3.0-5.3.2** 版本，请参考 [ACL 1.0
文档](07access-1.0.md)
+- **从 RocketMQ 5.3.3 开始，ACL 1.0 已不再支持**，建议升级到 ACL 2.0
+- 如果您正在从 ACL 1.0 迁移到 2.0，请查看本文档的 [ACL 1.0 迁移](#acl-10迁移到acl-20) 章节
+
+:::
+
+:::danger 安全提示
+
+⚠️ **本文档中的所有用户名、密码仅作为示例使用，切勿在生产环境中直接使用！**
+
+生产环境部署时，请务必：
+- 使用强密码（至少16位，包含大小写字母、数字和特殊字符）
+- 严格控制超级用户的使用范围
+- 妥善保管认证凭证，不要明文提交到代码仓库
-一般仅建议在网络环境不安全、业务数据敏感、多部门租户混用的场景下使用。如果生产集群本身是私有集群不会被外部部门租户访问，可以不开启。
:::
-## 2. 权限控制的定义与属性值
-### 2.1权限定义
-对RocketMQ的Topic资源访问权限控制定义主要如下表所示，分为以下四种
-
-| 权限 | 含义 |
-| --- | --- |
-| DENY | 拒绝 |
-| ANY | PUB 或者 SUB 权限 |
-| PUB | 发送权限 |
-| SUB | 订阅权限 |
-
-### 2.2 权限定义的关键属性
-| 字段 | 取值 | 含义 |
-| --- | --- | --- |
-| globalWhiteRemoteAddresses | \*;192.168.\*.\*;192.168.0.1 | 全局IP白名单 |
-| accessKey | 字符串 | Access Key |
-| secretKey | 字符串 | Secret Key |
-| whiteRemoteAddress | \*;192.168.\*.\*;192.168.0.1 | 用户IP白名单 |
-| admin | true;false | 是否管理员账户 |
-| defaultTopicPerm | DENY;PUB;SUB;PUB\|SUB | 默认的Topic权限 |
-| defaultGroupPerm | DENY;PUB;SUB;PUB\|SUB | 默认的ConsumerGroup权限 |
-| topicPerms | topic=权限 | 各个Topic的权限 |
-| groupPerms | group=权限 | 各个ConsumerGroup的权限 |
-
-具体可以参考**distribution/conf/plain_acl.yml**配置文件
-
-## 3. 支持权限控制的集群部署
-在**distribution/conf/plain_acl.yml**配置文件中按照上述说明定义好权限属性后，打开**aclEnable**开关变量即可开启RocketMQ集群的ACL特性。这里贴出Broker端开启ACL特性的properties配置文件内容：
+
+## 简介
+
+### 什么是RocketMQ ACL 2.0？
+
+RocketMQ ACL 2.0 是Apache RocketMQ的访问控制列表(Access Control
List)升级版本，提供了完善的身份认证(Authentication)和权限授权(Authorization)机制，用于保护RocketMQ集群的数据安全。
+
+### 核心特性
+
+- **双重安全机制**：支持认证和授权独立配置
+- **灵活的资源匹配**：支持完全匹配、前缀匹配和通配符匹配
+- **精细化权限控制**：覆盖集群、命名空间、Topic、Group等多种资源类型
+- **多种策略选择**：提供无状态和有状态两种认证授权策略
+- **组件间安全通信**：支持Broker、Proxy、NameServer等组件间的访问控制
+
+### 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **用户(User)** | 访问RocketMQ资源的主体，分为超级用户(Super)和普通用户(Normal) |
+| **资源(Resource)** | 需要访问控制的对象，如Cluster、Namespace、Topic、Group |
+| **操作(Action)** | 对资源执行的动作，如Pub、Sub、Create、Update、Delete、Get、List |
+| **决策(Decision)** | 授权结果，Allow(允许)或Deny(拒绝) |
+| **环境(Environment)** | 访问环境信息，如来源IP地址 |
+
+---
+
+## 快速开始
+
+### 5分钟快速体验
+
+本节将帮助您在5分钟内快速启动一个带ACL的RocketMQ集群。
+
+> **前提条件**:
+> - RocketMQ版本 ≥ 5.3.0
+> - 已完成RocketMQ的基本安装
+>
+> **版本检查**:
+> ```bash
+> # 查看RocketMQ版本
+> sh bin/mqbroker -v
+> ```
+
+> **说明**：本示例使用存算一体架构（单Broker模式），适合快速体验和测试环境。生产环境部署请参考[配置说明](#配置说明)章节。
+
+#### 第1步：配置Broker
+
+编辑 `conf/broker.conf` 文件，添加以下配置：
+
+```properties
+# 启用认证
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+
+# 启用授权
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+
+# 初始化管理员用户（首次启动自动创建）
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+
+# 组件间认证凭证（用于Broker主从同步、集群内部通信等）
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+> **配置说明**:
+> - 只需配置必填项即可快速启动，其他配置项都有默认值
+> - 生产环境建议配置 `authenticationStrategy` 和 `authorizationStrategy` 为有状态策略以提升性能
+
+#### 第2步：启动集群
+
+```bash
+# 1. 启动NameServer
+nohup sh bin/mqnamesrv &
+
+# 2. 启动Broker（使用上述配置文件）
+nohup sh bin/mqbroker -n localhost:9876 -c conf/broker.conf &
+```
+
+#### 第3步：配置mqadmin工具
+
+启用ACL后，需要配置mqadmin工具的认证凭证才能执行管理命令。
+
+编辑 `conf/tools.yml` 文件：
+
+```yaml
+# 使用初始化的管理员用户凭证
+accessKey: rocketmq
+secretKey: 12345678
+```
+
+#### 第4步：创建业务用户和授权
+
+```bash
+# 创建生产者用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u producer_user \
+ -p producer123 \
+ -t Normal
+
+# 授予Topic发送权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user \
+ -r Topic:TestTopic \
+ -a Pub \
+ -d Allow
+```
+
+#### 第5步：验证配置
+
+使用Java客户端发送一条测试消息：
+
+```java
+SessionCredentials credentials = new SessionCredentials("producer_user",
"producer123");
+StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ClientConfiguration clientConfiguration = ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:10911")
+ .setCredentialProvider(credentialsProvider)
+ .build();
+// ... 创建Producer并发送消息
+```
+
+✅ 恭喜！您已经成功启动了带ACL的RocketMQ集群。
+
+### 不同部署架构配置
+
+RocketMQ支持两种部署架构，根据您的场景选择合适的配置方案。
+
+#### 存算一体架构
+
+Broker同时负责计算和存储，适合中小规模集群和测试环境。
+
+**配置示例**：
+
+```properties
+# broker.conf
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+#### 存算分离架构（推荐）
+
+Proxy负责计算和认证授权，Broker仅负责存储和元数据管理，适合大规模生产环境。
+
+**Broker配置** (`broker.conf`):
+
+```properties
+# Broker只作为元数据提供者，不处理客户端认证授权
+authenticationEnabled = false
+authorizationEnabled = false
+
+# 配置元数据提供者
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+
+# 初始化管理员用户
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+```
+
+**Proxy配置** (`rmq-proxy.json`):
+
+```json
+{
+ "authenticationEnabled": true,
+ "authenticationProvider":
"org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider",
+ "authenticationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthenticationMetadataProvider",
+ "authenticationStrategy":
"org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy",
+
+ "authorizationEnabled": true,
+ "authorizationProvider":
"org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider",
+ "authorizationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthorizationMetadataProvider",
+ "authorizationStrategy":
"org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy"
+}
+```
+
+**启动顺序**:
+
+```bash
+# 1. 启动NameServer
+nohup sh bin/mqnamesrv &
+
+# 2. 启动Broker（存储节点）
+nohup sh bin/mqbroker -n localhost:9876 -c conf/broker.conf &
+
+# 3. 启动Proxy（计算节点）
+nohup sh bin/mqproxy -n localhost:9876 -pc conf/rmq-proxy.json &
+```
+
+---
+
+## 配置说明
+
+### 认证配置参数
+
+| 参数名称 | 类型 | 默认值 | 说明 |
+|---------|------|--------|------|
+| `authenticationEnabled` | boolean | `false` | 是否启用认证 |
+| `authenticationProvider` | String |
`org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider`
| 认证提供者实现类（可不配置，使用默认值） |
+| `authenticationMetadataProvider` | String | - | 认证元数据提供者实现类<br/>**必填项** |
+| `authenticationStrategy` | String |
`org.apache.rocketmq.auth.authentication.strategy.StatelessAuthenticationStrategy`
|
认证策略（可不配置，使用默认值）<br/>生产环境建议配置有状态策略：<br/>`org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy`
|
+| `initAuthenticationUser` | JSON | - |
**推荐配置**：系统初始化用户（首次启动自动创建）<br/>格式：`{"username":"xxx","password":"xxx"}`<br/>不配置则需手动创建管理员用户
|
+| `innerClientAuthenticationCredentials` | JSON | - |
**视情况配置**：组件间认证凭证，用于Broker主从同步、Proxy访问Broker、Controller选举等集群内部通信场景。<br/>格式：`{"accessKey":"xxx","secretKey":"xxx"}`<br/>⚠️如有组件间通信，所有组件必须配置完全相同的凭证
|
+| `authenticationWhitelist` | String | - | 认证白名单（IP列表，逗号分隔） |
+
+### 授权配置参数
+
+| 参数名称 | 类型 | 默认值 | 说明 |
+|---------|------|--------|------|
+| `authorizationEnabled` | boolean | `false` | 是否启用授权 |
+| `authorizationProvider` | String |
`org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider`
| 授权提供者实现类（可不配置，使用默认值） |
+| `authorizationMetadataProvider` | String | - | 授权元数据提供者实现类<br/>**必填项** |
+| `authorizationStrategy` | String |
`org.apache.rocketmq.auth.authorization.strategy.StatelessAuthorizationStrategy`
|
授权策略（可不配置，使用默认值）<br/>生产环境建议配置有状态策略：<br/>`org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy`
|
+| `authorizationWhitelist` | String | - | 授权白名单（IP列表，逗号分隔） |
+
+### 缓存配置参数
+
+| 参数名称 | 类型 | 默认值 | 说明 |
+|---------|------|--------|------|
+| `userCacheMaxNum` | int | `1000` | 用户缓存最大数量 |
+| `userCacheExpiredSecond` | int | `600` | 用户缓存过期时间(秒) |
+| `userCacheRefreshSecond` | int | `60` | 用户缓存刷新时间(秒) |
+| `aclCacheMaxNum` | int | `1000` | ACL缓存最大数量 |
+| `aclCacheExpiredSecond` | int | `600` | ACL缓存过期时间(秒) |
+| `aclCacheRefreshSecond` | int | `60` | ACL缓存刷新时间(秒) |
+| `statefulAuthenticationCacheMaxNum` | int | `10000` | 有状态认证缓存最大数量 |
+| `statefulAuthenticationCacheExpiredSecond` | int | `60` | 有状态认证缓存过期时间(秒) |
+| `statefulAuthorizationCacheMaxNum` | int | `10000` | 有状态授权缓存最大数量 |
+| `statefulAuthorizationCacheExpiredSecond` | int | `60` | 有状态授权缓存过期时间(秒) |
+
+### 认证授权策略
+
+#### 无状态策略 (Stateless) - 默认策略
+
+- **特点**：每个请求都进行完整的认证和授权检查
+- **优势**：安全性高，权限变更立即生效
+- **劣势**：性能开销较大
+- **适用场景**：安全要求极高的环境
+- **默认值**：✅ 系统默认使用此策略
+
+**配置示例**:
+
```properties
-brokerClusterName=DefaultCluster
-brokerName=broker-a
-brokerId=0
-deleteWhen=04
-fileReservedTime=48
-brokerRole=ASYNC_MASTER
-flushDiskType=ASYNC_FLUSH
-storePathRootDir=/data/rocketmq/rootdir-a-m
-storePathCommitLog=/data/rocketmq/commitlog-a-m
-autoCreateSubscriptionGroup=true
-## if acl is open,the flag will be true
-aclEnable=true
-listenPort=10911
-brokerIP1=XX.XX.XX.XX1
-namesrvAddr=XX.XX.XX.XX:9876
+# 以下为默认值，可不配置
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatelessAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatelessAuthorizationStrategy
+```
+
+#### 有状态策略 (Stateful) - 生产环境推荐
+
+- **特点**：首次请求进行认证授权，后续请求使用缓存结果
+- **优势**：性能开销小，吞吐量高
+- **劣势**：权限变更有延迟（缓存过期后生效）
+- **适用场景**：高吞吐量场景，生产环境推荐
+- **推荐使用**：⭐ 生产环境建议显式配置此策略
+
+**配置示例**:
+
+```properties
+# 生产环境推荐配置
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+```
+
+---
+
+## 用户管理
+
+### 用户类型说明
+
+| 用户类型 | 说明 | 权限范围 | 使用场景 |
+|---------|------|---------|---------|
+| **Super** | 超级用户 | 拥有所有资源的所有权限，无需单独授权 | 系统管理员、运维人员 |
+| **Normal** | 普通用户 | 需要显式授权才能访问资源 | 业务应用、服务 |
+
+### mqadmin工具配置
+
+使用mqadmin命令行工具前，需要配置管理员凭证。
+
+**配置文件**: `conf/tools.yml`
+
+```yaml
+# 使用超级用户的用户名和密码
+accessKey: rocketmq
+secretKey: 12345678
+```
+
+**验证配置**:
+
+```bash
+# 测试mqadmin工具是否能正常连接
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+```
+
+### 用户管理命令
+
+#### 创建用户
+
+```bash
+# 创建普通用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
password -t Normal
+
+# 创建超级用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster -u rocketmq -p
12345678 -t Super
+```
+
+#### 更新用户
+
+```bash
+# 修改用户密码
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
newpassword
+
+# 修改用户类型
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -t
Super
+```
+
+#### 查询用户
+
+```bash
+# 查询用户详情
+sh bin/mqadmin getUser -n 127.0.0.1:9876 -c DefaultCluster -u username
+
+# 查询用户列表
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+
+# 查询用户列表（带过滤）
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster -f producer
+```
+
+#### 删除用户
+
+```bash
+sh bin/mqadmin deleteUser -n 127.0.0.1:9876 -c DefaultCluster -u username
```
-## 4. 权限控制主要流程
-ACL主要流程分为两部分，主要包括权限解析和权限校验。
+### 命令参数说明
+
+| 参数 | 必填 | 说明 | 默认值 |
+|------|------|------|--------|
+| `-n` | 是 | NameServer地址 | - |
+| `-c` | 否 | 集群名称（与`-b`二选一） | - |
+| `-b` | 否 | Broker地址（与`-c`二选一） | - |
+| `-u` | 是 | 用户名 | - |
+| `-p` | 否 | 密码（创建/更新时使用） | - |
+| `-t` | 否 | 用户类型：Super或Normal | Normal |
+| `-f` | 否 | 过滤条件（查询时使用） | - |
+
+---
+
+## 权限管理
+
+### 核心概念
+
+#### 资源类型
+
+| 资源类型 | 格式 | 示例 | 说明 |
+|---------|------|------|------|
+| **Any** | `*` | `*` | 所有资源 |
+| **Cluster** | `Cluster:集群名` | `Cluster:DefaultCluster` | 集群级资源 |
+| **Namespace** | `Namespace:命名空间` | `Namespace:test` | 命名空间 |
+| **Topic** | `Topic:主题名` | `Topic:TestTopic` | 消息主题 |
+| **Group** | `Group:消费组名` | `Group:TestGroup` | 消费者组 |
+
+#### 资源匹配模式
+
+| 匹配模式 | 说明 | 示例 | 匹配结果 |
+|---------|------|------|---------|
+| **完全匹配(LITERAL)** | 精确匹配资源名称 | `Topic:OrderTopic` | 仅匹配`Topic:OrderTopic` |
+| **前缀匹配(PREFIXED)** | 匹配指定前缀的资源 | `Topic:Order*` |
匹配`Topic:OrderTopic`、`Topic:OrderDLQTopic`等 |
+| **通配符匹配(ANY)** | 匹配该类型的所有资源 | `Topic:*` | 匹配所有Topic |
+
+#### 操作类型
+
+| 操作 | 说明 | 适用资源 |
+|------|------|---------|
+| **Pub** | 发布消息 | Topic |
+| **Sub** | 订阅消息 | Topic, Group |
+| **Create** | 创建资源 | Cluster, Namespace, Topic, Group |
+| **Update** | 更新资源 | Cluster, Namespace, Topic, Group |
+| **Delete** | 删除资源 | Cluster, Namespace, Topic, Group |
+| **Get** | 查询资源详情 | Cluster, Namespace, Topic, Group |
+| **List** | 查询资源列表 | Cluster, Namespace, Topic, Group |
+| **All** | 所有操作 | 所有资源 |
+
+#### 决策类型
+
+| 决策 | 说明 |
+|------|------|
+| **Allow** | 允许执行操作 |
+| **Deny** | 拒绝执行操作（优先级高于Allow） |
-### 4.1 权限解析
-Broker端对客户端的RequestCommand请求进行解析，拿到需要鉴权的属性字段。
-主要包括：
-（1）AccessKey：类似于用户名，代指用户主体，权限数据与之对应；
-（2）Signature：客户根据 SecretKey 签名得到的串，服务端再用SecretKey进行签名验证；
-### 4.2 权限校验
-Broker端对权限的校验逻辑主要分为以下几步：
-（1）检查是否命中全局 IP 白名单；如果是，则认为校验通过；否则走 2；
-（2）检查是否命中用户 IP 白名单；如果是，则认为校验通过；否则走 3；
-（3）校验签名，校验不通过，抛出异常；校验通过，则走 4；
-（4）对用户请求所需的权限 和 用户所拥有的权限进行校验；不通过，抛出异常；
-用户所需权限的校验需要注意已下内容：
-（1）特殊的请求例如 UPDATE_AND_CREATE_TOPIC 等，只能由 admin 账户进行操作；
-（2）对于某个资源，如果有显性配置权限，则采用配置的权限；如果没有显性配置权限，则采用默认的权限；
+### 权限优先级规则
-## 5. 热加载修改后权限控制定义
-RocketMQ的权限控制存储的默认实现是基于yml配置文件。用户可以动态修改权限控制定义的属性，而不需重新启动Broker服务节点。
+当多个权限策略匹配同一请求时，按以下优先级确定最终结果。
-## 6. 权限控制的使用限制
-(1)如果ACL与高可用部署(Master/Slave架构)同时启用，那么需要在Broker
Master节点的distribution/conf/plain_acl.yml配置文件中
-设置全局白名单信息，即为将Slave节点的ip地址设置至Master节点plain_acl.yml配置文件的全局白名单中。
+#### 优先级规则
-(2)如果ACL与高可用部署(多副本Dledger架构)同时启用，由于出现节点宕机时，Dledger Group组内会自动选主，那么就需要将Dledger
Group组
-内所有Broker节点的plain_acl.yml配置文件的白名单设置所有Broker节点的ip地址。
+|| 资源优先级（高→低） | 决策优先级 |
+||------------------|----------|
+|| 1. 具体资源类型 > 任意资源类型(`*`)<br/>2. 完全匹配 > 前缀匹配 > 通配符匹配<br/>3. 长资源名 > 短资源名 |
**Deny > Allow**<br/>（拒绝优先级高于允许） |
-## 7. ACL mqadmin配置管理命令
+#### 优先级示例
-### 7.1 更新ACL配置文件中“account”的属性值
+|| 策略 | 资源定义 | 操作 | 决策 | 优先级 |
+||------|---------|------|------|--------|
+|| 1 | `Topic:test-abc-1` | Pub,Sub | Deny | 最高 |
+|| 2 | `Topic:test-abc` | Pub,Sub | Allow | 高 |
+|| 3 | `Topic:test-*` | Pub,Sub | Allow | 中 |
+|| 4 | `Topic:*` | Pub,Sub | Allow | 低 |
+|| 5 | `*` | All | Deny | 最低 |
-该命令的示例如下：
+**匹配结果**：
-```shell
-$ sh mqadmin updateAclConfig -n 192.168.1.2:9876 -b 192.168.12.134:10911 -a
RocketMQ -s 1234567809123 -t topicA=DENY,topicD=SUB -g groupD=DENY,groupB=SUB
+|| 访问资源 | 匹配策略 | 最终决策 |
+||---------|---------|---------|
+|| `Topic:test-abc-1` | 策略1（完全匹配） | ❌ Deny |
+|| `Topic:test-abc` | 策略2（完全匹配） | ✅ Allow |
+|| `Topic:test-123` | 策略3（前缀匹配） | ✅ Allow |
+|| `Topic:other` | 策略4（通配符匹配） | ✅ Allow |
+|| `Group:TestGroup` | 策略5（任意资源） | ❌ Deny |
+
+### 权限管理命令
+
+#### 创建权限
+
+**基本用法示例**：
+
+```bash
+# 示例1：授予单个Topic的发布权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -d Allow
+
+# 示例2：授予单个Topic的订阅权限（需要同时指定Topic和Group）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:consumer_user -r Topic:TestTopic,Group:TestGroup -a Sub -d Allow
+
+# 示例3：授予多个操作权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user -r Topic:TestTopic -a Create,Update,Delete,Get,List -d
Allow
```
-说明：如果不存在则会在ACL Config YAML配置文件中创建；若存在，则会更新对应的“accounts”的属性值;
-如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
+**资源匹配模式示例**：
+
+```bash
+# 示例4：完全匹配 - 精确匹配资源名称
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:OrderTopic -a Pub,Sub -d Allow
-| 参数 | 取值 | 含义 |
-| --- | --- | --- |
-| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
-| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
-| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
-| a | eg:RocketMQ | Access Key值(必填) |
-| s | eg:1234567809123 | Secret Key值(可选) |
-| m | eg:true | 是否管理员账户(可选) |
-| w | eg:192.168.0.* | whiteRemoteAddress,用户IP白名单(可选) |
-| i | eg:DENY;PUB;SUB;PUB\|SUB | defaultTopicPerm,默认Topic权限(可选) |
-| u | eg:DENY;PUB;SUB;PUB\|SUB | defaultGroupPerm,默认ConsumerGroup权限(可选) |
-| t | eg:topicA=DENY,topicD=SUB | topicPerms,各个Topic的权限(可选) |
-| g | eg:groupD=DENY,groupB=SUB | groupPerms,各个ConsumerGroup的权限(可选) |
+# 示例5：前缀匹配 - 匹配所有order_开头的Topic
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:order_* -a Pub -d Allow
-### 7.2 删除ACL配置文件里面的对应“account”
-该命令的示例如下：
+# 示例6：通配符匹配 - 匹配所有Topic
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:monitor_user -r Topic:* -a Get,List -d Allow
-```shell
-$ sh mqadmin deleteAccessConfig -n 192.168.1.2:9876 -c DefaultCluster -a
RocketMQ
+# 示例7：匹配所有资源类型
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:super_admin -r * -a All -d Allow
```
-说明：如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
-其中，参数"a"为Access Key的值，用以标识唯一账户id，因此该命令的参数中指定账户id即可。
+**IP白名单示例**：
+
+```bash
+# 示例8：限制单个IP访问
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -i 192.168.1.100 -d Allow
-| 参数 | 取值 | 含义 |
-| --- | --- | --- |
-| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
-| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
-| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
-| a | eg:RocketMQ | Access Key的值(必填) |
+# 示例9：限制IP段访问（CIDR格式）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:internal_user -r Topic:InternalTopic -a Pub,Sub -i 192.168.1.0/24 -d
Allow
+
+# 示例10：不限制IP（不指定-i参数）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:public_user -r Topic:PublicTopic -a Pub -d Allow
+```
+**拒绝策略示例**：
-### 7.3 更新ACL配置文件里面中的全局白名单
-该命令的示例如下：
+```bash
+# 示例11：拒绝访问敏感Topic
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:SensitiveTopic -a Pub,Sub -d Deny
-```shell
-$ sh mqadmin updateGlobalWhiteAddr -n 192.168.1.2:9876 -b 192.168.12.134:10911
-g 10.10.154.1,10.10.154.2
+# 示例12：先授予大部分权限，再拒绝特定资源（Deny优先级更高）
+# 第一步：授予所有Topic访问权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:* -a Pub,Sub -d Allow
+# 第二步：拒绝敏感Topic（会覆盖上面的Allow）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user -r Topic:SensitiveTopic -a Pub,Sub -d Deny
```
-说明：如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
-其中，参数"g"为全局IP白名的值，用以更新ACL配置文件中的“globalWhiteRemoteAddresses”字段的属性值。
+**集群管理权限示例**：
-| 参数 | 取值 | 含义 |
-| --- | --- | --- |
-| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
-| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
-| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
-| g | eg:10.10.154.1,10.10.154.2 | 全局IP白名单(必填) |
+```bash
+# 示例13：授予集群查询权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:monitor_user -r Cluster:DefaultCluster -a Get,List -d Allow
-### 7.4 查询集群/Broker的ACL配置文件版本信息
-该命令的示例如下：
+# 示例14：授予Topic管理权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:topic_admin -r Topic:* -a Create,Update,Delete,Get,List -d Allow
-```shell
-$ sh mqadmin clusterAclConfigVersion -n 192.168.1.2:9876 -c DefaultCluster
+# 示例15：授予Group管理权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:group_admin -r Group:* -a Create,Update,Delete,Get,List -d Allow
```
-说明：如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
+#### 更新权限
-| 参数 | 取值 | 含义 |
-| --- | --- | --- |
-| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
-| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
-| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
+```bash
+sh bin/mqadmin updateAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub,Sub -d Allow
+```
+
+#### 查询权限
+
+```bash
+# 查询用户的所有权限
+sh bin/mqadmin getAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:producer_user
-### 7.5 查询集群/Broker的ACL配置文件全部内容
-该命令的示例如下：
+# 查询所有权限列表
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster
-```shell
-$ sh mqadmin getAccessConfigSubCommand -n 192.168.1.2:9876 -c DefaultCluster
+# 查询权限列表（带过滤条件）
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user -r Topic:TestTopic
```
-说明：如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
+#### 删除权限
+
+```bash
+# 删除用户的所有权限
+sh bin/mqadmin deleteAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user
+
+# 删除用户对特定资源的权限
+sh bin/mqadmin deleteAcl -n 127.0.0.1:9876 -c DefaultCluster -s
User:producer_user -r Topic:TestTopic
+```
+
+### 命令参数说明
+
+| 参数 | 必填 | 说明 | 示例 |
+|------|------|------|------|
+| `-n` | 是 | NameServer地址 | `127.0.0.1:9876` |
+| `-c` | 否 | 集群名称（与`-b`二选一） | `DefaultCluster` |
+| `-b` | 否 | Broker地址（与`-c`二选一） | `192.168.1.1:10911` |
+| `-s` | 是 | 主体名称 | `User:producer_user` |
+| `-r` | 否 | 资源定义（多个用逗号分隔） |
`Topic:TestTopic`<br/>`Topic:*`<br/>`Topic:Order*,Group:Order*` |
+| `-a` | 否 | 操作类型（多个用逗号分隔） | `Pub`<br/>`Pub,Sub`<br/>`Create,Update,Delete` |
+| `-i` | 否 | IP白名单（支持IP或IP段） | `192.168.1.100`<br/>`192.168.1.0/24` |
+| `-d` | 否 | 决策结果 | `Allow` 或 `Deny` |
+
+
+---
+
+## 客户端使用
+
+### Java客户端配置
+
+#### Maven依赖
+
+```xml
+<dependency>
+ <groupId>org.apache.rocketmq</groupId>
+ <artifactId>rocketmq-client-java</artifactId>
+ <version>5.3.4</version>
+</dependency>
+```
+
+### 消息生产者
+
+```java
+import org.apache.rocketmq.client.apis.ClientConfiguration;
+import org.apache.rocketmq.client.apis.ClientServiceProvider;
+import org.apache.rocketmq.client.apis.SessionCredentials;
+import org.apache.rocketmq.client.apis.StaticSessionCredentialsProvider;
+import org.apache.rocketmq.client.apis.producer.Producer;
+import org.apache.rocketmq.client.apis.message.Message;
+
+public class ProducerWithACL {
+ public static void main(String[] args) throws Exception {
+ // 1. 创建凭证提供者
+ SessionCredentials credentials = new SessionCredentials(
+ "producer_user", // AccessKey (用户名)
+ "producer123" // SecretKey (密码)
+ );
+ StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ // 2. 配置客户端
+ ClientConfiguration clientConfiguration =
ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:8081") // Proxy地址或Broker地址
+ .setCredentialProvider(credentialsProvider)
+ .build();
+
+ // 3. 创建生产者
+ ClientServiceProvider provider = ClientServiceProvider.loadService();
+ Producer producer = provider.newProducerBuilder()
+ .setClientConfiguration(clientConfiguration)
+ .setTopics("TestTopic")
+ .build();
+
+ // 4. 发送消息
+ Message message = provider.newMessageBuilder()
+ .setTopic("TestTopic")
+ .setBody("Hello RocketMQ with ACL".getBytes())
+ .build();
+
+ producer.send(message);
+ System.out.println("消息发送成功");
+
+ // 5. 关闭生产者
+ producer.close();
+ }
+}
+```
+
+### 消息消费者
+
+```java
+import org.apache.rocketmq.client.apis.ClientConfiguration;
+import org.apache.rocketmq.client.apis.ClientServiceProvider;
+import org.apache.rocketmq.client.apis.SessionCredentials;
+import org.apache.rocketmq.client.apis.StaticSessionCredentialsProvider;
+import org.apache.rocketmq.client.apis.consumer.PushConsumer;
+import org.apache.rocketmq.client.apis.consumer.FilterExpression;
+import org.apache.rocketmq.client.apis.consumer.FilterExpressionType;
+import org.apache.rocketmq.client.apis.consumer.ConsumeResult;
+
+import java.util.Collections;
+
+public class ConsumerWithACL {
+ public static void main(String[] args) throws Exception {
+ // 1. 创建凭证提供者
+ SessionCredentials credentials = new SessionCredentials(
+ "consumer_user", // AccessKey (用户名)
+ "consumer123" // SecretKey (密码)
+ );
+ StaticSessionCredentialsProvider credentialsProvider =
+ new StaticSessionCredentialsProvider(credentials);
+
+ // 2. 配置客户端
+ ClientConfiguration clientConfiguration =
ClientConfiguration.newBuilder()
+ .setEndpoints("127.0.0.1:8081")
+ .setCredentialProvider(credentialsProvider)
+ .build();
+
+ // 3. 创建消费者
+ ClientServiceProvider provider = ClientServiceProvider.loadService();
+ FilterExpression filterExpression = new FilterExpression("*",
FilterExpressionType.TAG);
+
+ PushConsumer consumer = provider.newPushConsumerBuilder()
+ .setClientConfiguration(clientConfiguration)
+ .setConsumerGroup("TestGroup")
+ .setSubscriptionExpressions(Collections.singletonMap("TestTopic",
filterExpression))
+ .setMessageListener(messageView -> {
+ System.out.println("接收消息: " + new
String(messageView.getBody().array()));
+ return ConsumeResult.SUCCESS;
+ })
+ .build();
+
+ System.out.println("消费者启动成功");
+
+ // 保持运行
+ Thread.sleep(Long.MAX_VALUE);
+ }
+}
+```
+
+### Spring Boot集成
+
+```yaml
+# application.yml
+rocketmq:
+ name-server: 127.0.0.1:9876
+ producer:
+ group: producer-group
+ access-key: producer_user
+ secret-key: producer123
+ consumer:
+ group: consumer-group
+ access-key: consumer_user
+ secret-key: consumer123
+ topics:
+ - TestTopic
+```
+
+---
+
+## 常见场景
+
+### 场景1：生产者和消费者分离
+
+**需求**: 生产者只能发送消息，消费者只能消费消息
+
+```bash
+# 创建生产者用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u producer_user -p producer123 -t Normal
+
+# 创建消费者用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u consumer_user -p consumer123 -t Normal
+
+# 授予生产者发送权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:producer_user -r Topic:TestTopic -a Pub -d Allow
+
+# 授予消费者消费权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:consumer_user -r Topic:TestTopic,Group:TestGroup -a Sub -d Allow
+```
+
+### 场景2：按业务模块划分权限
+
+**需求**: 不同业务模块使用不同的Topic前缀，各模块用户只能访问自己的Topic
+
+```bash
+# 创建订单模块用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u order_service -p order123 -t Normal
+
+# 授予订单模块权限（可以访问所有order_开头的Topic）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:order_service -r Topic:order_* -a Pub,Sub -d Allow
+
+# 创建支付模块用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u payment_service -p payment123 -t Normal
+
+# 授予支付模块权限（可以访问所有payment_开头的Topic）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:payment_service -r Topic:payment_* -a Pub,Sub -d Allow
+```
+
+### 场景3：IP白名单限制
+
+**需求**: 只允许特定IP段的机器访问
+
+```bash
+# 创建用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u internal_user -p internal123 -t Normal
+
+# 授予权限，但限制只能从内网IP访问
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:internal_user \
+ -r Topic:InternalTopic \
+ -a Pub,Sub \
+ -i 192.168.1.0/24,10.0.0.0/8 \
+ -d Allow
+```
+
+### 场景4：管理员权限
+
+**需求**: 管理员需要管理Topic和Group的创建、更新、删除
+
+```bash
+# 创建管理员用户
+sh bin/mqadmin createUser -n 127.0.0.1:9876 -c DefaultCluster \
+ -u admin_user -p admin_user123 -t Normal
+
+# 授予集群管理权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Cluster:DefaultCluster \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
+
+# 授予所有Topic的管理权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Topic:* \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
+
+# 授予所有Group的管理权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:admin_user \
+ -r Group:* \
+ -a Create,Update,Delete,Get,List \
+ -d Allow
+```
+
+### 场景5：拒绝访问敏感Topic
+
+**需求**: 明确拒绝某些用户访问敏感Topic
+
+```bash
+# 授予用户访问大部分Topic的权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user \
+ -r Topic:* \
+ -a Pub,Sub \
+ -d Allow
+
+# 拒绝访问敏感Topic（Deny优先级高于Allow）
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:normal_user \
+ -r Topic:SensitiveTopic \
+ -a Pub,Sub \
+ -d Deny
+```
+
+---
+
+## 故障排查
+
+### 常见错误
+
+#### 1. mqadmin工具执行命令失败
+
+**错误信息**:
+```
+CODE: 17 DESC: No user
+或
+CODE: 16 DESC: Authentication failed
+```
+
+**可能原因**:
+- 未配置 `conf/tools.yml` 文件
+- `tools.yml` 中的凭证配置错误
+- 配置的用户不是超级用户
+
+**解决方案**:
+```bash
+# 1. 检查 tools.yml 文件是否存在
+ls conf/tools.yml
+
+# 2. 配置管理员凭证
+cat > conf/tools.yml << EOF
+accessKey: rocketmq
+secretKey: 12345678
+EOF
+
+# 3. 验证配置
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+```
+
+#### 2. 客户端认证失败
+
+**错误信息**:
+```
+[AUTHENTICATION] User:xxx is authenticated failed with Signature = xxx
+```
+
+**可能原因**:
+- 用户名或密码错误
+- 用户不存在
+- 用户被禁用
+
+**排查步骤**:
+```bash
+# 1. 检查用户是否存在
+sh bin/mqadmin getUser -n 127.0.0.1:9876 -c DefaultCluster -u username
+
+# 2. 检查客户端配置的用户名密码是否正确
+
+# 3. 重置用户密码
+sh bin/mqadmin updateUser -n 127.0.0.1:9876 -c DefaultCluster -u username -p
newpassword
+```
+
+#### 3. 授权失败
+
+**错误信息**:
+```
+[AUTHORIZATION] Subject = User:xxx is Deny Action = Pub from sourceIp = xxx on
resource = Topic:xxx
+```
+
+**可能原因**:
+- 用户没有对应资源的权限
+- IP不在白名单内
+- 存在Deny规则
+
+**排查步骤**:
+```bash
+# 1. 检查用户的权限配置
+sh bin/mqadmin getAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:username
+
+# 2. 检查是否有Deny规则
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster -s User:username
+
+# 3. 授予相应权限
+sh bin/mqadmin createAcl -n 127.0.0.1:9876 -c DefaultCluster \
+ -s User:username -r Topic:TestTopic -a Pub -d Allow
+```
+
+#### 4. 组件间通信失败
+
+**错误信息**:
+```
+Slave Broker connect to Master failed
+或
+Proxy connect to Broker failed
+```
+
+**可能原因**:
+- `innerClientAuthenticationCredentials` 配置错误
+- 不同组件间的认证凭证不一致
+- Master/Slave的凭证配置不匹配
+
+**解决方案**:
+```bash
+# 检查所有组件的配置是否一致
+grep "innerClientAuthenticationCredentials" conf/*.conf conf/*.json
+
+# 修改为统一的凭证
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+```
+
+### 查看审计日志
+
+认证和授权的所有操作都会记录在Broker/Proxy的日志中。
+
+**查看认证日志**:
+```bash
+grep "AUTHENTICATION" logs/rocketmqlogs/broker.log
+
+# 认证成功示例
+# [AUTHENTICATION] User:producer_user is authenticated success with Signature
= xxx
+
+# 认证失败示例
+# [AUTHENTICATION] User:producer_user is authenticated failed with Signature =
xxx
+```
+
+**查看授权日志**:
+```bash
+grep "AUTHORIZATION" logs/rocketmqlogs/broker.log
+
+# 授权成功示例
+# [AUTHORIZATION] Subject = User:producer_user is Allow Action = Pub from
sourceIp = 192.168.1.100 on resource = Topic:TestTopic
+
+# 授权失败示例
+# [AUTHORIZATION] Subject = User:producer_user is Deny Action = Sub from
sourceIp = 192.168.1.100 on resource = Topic:TestTopic
+```
+
+---
+
+## 最佳实践
+
+### 1. 用户管理
+
+✅ **推荐做法**:
+- 为不同的应用或服务创建独立的用户
+- 使用强密码（至少8位，包含字母和数字）
+- 超级用户仅用于系统初始化和紧急运维
+
+❌ **避免做法**:
+- 多个应用共享同一个用户
+- 使用弱密码（如123456）
+- 在生产环境大量使用超级用户
+
+### 2. 权限配置
+
+✅ **推荐做法**:
+- 遵循最小权限原则，只授予必要的权限
+- 使用前缀匹配简化同类资源的权限管理
+- 对敏感资源使用Deny规则进行保护
+- 生产者只授予Pub权限，消费者只授予Sub权限
+
+❌ **避免做法**:
+- 给所有用户授予`*`资源的All权限
+- 过度使用通配符匹配
+- 忽略IP白名单配置
+
+### 3. 策略选择
+
+**选择无状态策略的场景**:
+- 金融、支付等对安全要求极高的场景
+- 权限变更需要立即生效的场景
+- 低吞吐量场景
+
+**选择有状态策略的场景**:
+- 电商、日志等高吞吐量场景
+- 权限变更不频繁的场景
+- 对性能要求较高的场景
+
+### 4. 生产环境部署调优
+
+在生产环境部署时，除了基本配置外（参考[快速开始](#快速开始)），还需要关注以下参数调优。
+
+#### 存算一体架构调优
+
+```properties
+# broker.conf
+# 基本配置
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+
+# 生产环境性能调优：使用有状态策略（默认为无状态）
+authenticationStrategy =
org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy
+authorizationStrategy =
org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy
+
+# 缓存配置（根据用户数量和QPS调整）
+userCacheMaxNum = 5000
+userCacheExpiredSecond = 3600
+userCacheRefreshSecond = 300
+aclCacheMaxNum = 5000
+aclCacheExpiredSecond = 3600
+aclCacheRefreshSecond = 300
+statefulAuthenticationCacheMaxNum = 20000
+statefulAuthenticationCacheExpiredSecond = 60
+statefulAuthorizationCacheMaxNum = 20000
+statefulAuthorizationCacheExpiredSecond = 60
+```
+
+#### 存算分离架构调优（推荐）
+
+**Broker配置** (`broker.conf`):
+
+```properties
+# Broker仅作为元数据提供者
+authenticationEnabled = false
+authorizationEnabled = false
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+```
+
+**Proxy配置** (`rmq-proxy.json`):
+
+```json
+{
+ "authenticationEnabled": true,
+ "authenticationProvider":
"org.apache.rocketmq.auth.authentication.provider.DefaultAuthenticationProvider",
+ "authenticationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthenticationMetadataProvider",
+ "authenticationStrategy":
"org.apache.rocketmq.auth.authentication.strategy.StatefulAuthenticationStrategy",
+
+ "authorizationEnabled": true,
+ "authorizationProvider":
"org.apache.rocketmq.auth.authorization.provider.DefaultAuthorizationProvider",
+ "authorizationMetadataProvider":
"org.apache.rocketmq.proxy.auth.ProxyAuthorizationMetadataProvider",
+ "authorizationStrategy":
"org.apache.rocketmq.auth.authorization.strategy.StatefulAuthorizationStrategy",
+
+ "userCacheMaxNum": 5000,
+ "userCacheExpiredSecond": 3600,
+ "userCacheRefreshSecond": 300,
+ "aclCacheMaxNum": 5000,
+ "aclCacheExpiredSecond": 3600,
+ "aclCacheRefreshSecond": 300,
+ "statefulAuthenticationCacheMaxNum": 20000,
+ "statefulAuthenticationCacheExpiredSecond": 60,
+ "statefulAuthorizationCacheMaxNum": 20000,
+ "statefulAuthorizationCacheExpiredSecond": 60
+}
+```
+
+**调优建议**:
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| `userCacheMaxNum` | 用户数 × 1.5 | 避免频繁加载用户数据 |
+| `aclCacheMaxNum` | 用户数 × 1.5 | 避免频繁加载权限数据 |
+| `statefulAuthenticationCacheMaxNum` | 连接数 × 2 | 缓存每个连接的认证结果 |
+| `statefulAuthorizationCacheMaxNum` | 连接数 × 资源数 × 2 | 缓存每个连接对每个资源的授权结果 |
+
+### 5. ACL 1.0迁移到ACL 2.0
+
+**迁移步骤**:
+
+```bash
+# 1. 备份ACL 1.0配置
+cp conf/plain_acl.yml conf/plain_acl.yml.backup
+
+# 2. 在Broker配置中启用迁移
+echo "migrateAuthFromV1Enabled = true" >> conf/broker.conf
+
+# 3. 启用ACL 2.0
+cat >> conf/broker.conf << EOF
+authenticationEnabled = true
+authenticationMetadataProvider =
org.apache.rocketmq.auth.authentication.provider.LocalAuthenticationMetadataProvider
+authorizationEnabled = true
+authorizationMetadataProvider =
org.apache.rocketmq.auth.authorization.provider.LocalAuthorizationMetadataProvider
+initAuthenticationUser = {"username":"rocketmq","password":"12345678"}
+innerClientAuthenticationCredentials =
{"accessKey":"rocketmq","secretKey":"12345678"}
+EOF
+
+# 4. 重启Broker（迁移会在启动时自动执行）
+sh bin/mqbroker -n localhost:9876 -c conf/broker.conf
+
+# 5. 验证迁移结果
+sh bin/mqadmin listUser -n 127.0.0.1:9876 -c DefaultCluster
+sh bin/mqadmin listAcl -n 127.0.0.1:9876 -c DefaultCluster
+
+# 6. 迁移成功后，关闭迁移开关
+# migrateAuthFromV1Enabled = false
+
+# 7. 删除旧配置文件（可选）
+rm conf/plain_acl.yml
+```
+
+**注意事项**:
+- ACL 1.0的IP白名单不会迁移（行为不一致）
+- 已存在的用户和权限不会被覆盖
+- 建议在测试环境先验证迁移效果
+- 迁移成功后建议删除 `plain_acl.yml` 文件，避免混淆
+
+### 6. 扩容新Broker
+
+当集群扩容新Broker时，需要同步用户和权限数据。
+
+**从旧Broker拷贝所有用户到新Broker**：
+
+```bash
+# 拷贝所有用户
+sh bin/mqadmin copyUser -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911
+
+# 拷贝所有权限
+sh bin/mqadmin copyAcl -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911
+```
+
+**从旧Broker拷贝特定用户到新Broker**：
+
+```bash
+# 拷贝特定用户
+sh bin/mqadmin copyUser -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911 -u producer_user
+
+# 拷贝该用户的权限
+sh bin/mqadmin copyAcl -n 127.0.0.1:9876 -f 192.168.0.1:10911 -t
192.168.0.2:10911 -s User:producer_user
+```
+
+### 7. 监控和告警
+
+**建议监控指标**:
+- 认证失败次数
+- 授权拒绝次数
+- 缓存命中率
+- 用户数量
+- ACL规则数量
-| 参数 | 取值 | 含义 |
-| --- | --- | --- |
-| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
-| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
-| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
+**日志监控脚本示例**:
+```bash
+#!/bin/bash
+# 监控认证失败次数
+auth_fail_count=$(grep "authenticated failed" logs/rocketmqlogs/broker.log |
wc -l)
+if [ $auth_fail_count -gt 100 ]; then
+ echo "告警：认证失败次数过多: $auth_fail_count"
+fi
-**特别注意**开启Acl鉴权认证后导致Master/Slave和Dledger模式下Broker同步数据异常的问题，
-在社区[4.5.1]版本中已经修复，具体的PR链接为：https://github.com/apache/rocketmq/pull/1149；
\ No newline at end of file
+# 监控授权拒绝次数
+authz_deny_count=$(grep "is Deny" logs/rocketmqlogs/broker.log | wc -l)
+if [ $authz_deny_count -gt 100 ]; then
+ echo "告警：授权拒绝次数过多: $authz_deny_count"
+fi
+```
\ No newline at end of file
diff --git a/versioned_docs/version-5.0/06-bestPractice/03access.md
b/versioned_docs/version-5.0/06-bestPractice/07access-1.0.md
similarity index 88%
copy from versioned_docs/version-5.0/06-bestPractice/03access.md
copy to versioned_docs/version-5.0/06-bestPractice/07access-1.0.md
index fb15354045..abfe47a397 100644
--- a/versioned_docs/version-5.0/06-bestPractice/03access.md
+++ b/versioned_docs/version-5.0/06-bestPractice/07access-1.0.md
@@ -1,17 +1,28 @@
-# 权限控制
+---
+unlisted: true
+---
-## 1.权限控制特性介绍
-权限控制（ACL）主要为 RocketMQ 提供 Topic
资源级别的高级访问控制功能。用户在使用RocketMQ权限控制时，可以在Client客户端注入用户名和密码参数实现签名，服务端通过权限控制参数实现各个资源的权限管理和校验。
+# 权限控制（ACL 1.0）
+
+:::warning 历史版本文档
+
+本文档介绍的是 **RocketMQ ACL 1.0**，适用于 **RocketMQ 4.x、5.0-5.2 和 5.3.0-5.3.2** 版本。
+
+**从 RocketMQ 5.3.3 开始，ACL 1.0 已被移除，不再支持。**
-:::info
-ACL控制在增强集群访问控制安全性的同时也会带来部署流程和运维管理的复杂度。
+如果您使用的是 **RocketMQ 5.3.0** 及以上版本，强烈建议使用 [ACL 2.0
文档](03access.md)，它提供了更强大和灵活的权限控制功能。
-一般仅建议在网络环境不安全、业务数据敏感、多部门租户混用的场景下使用。如果生产集群本身是私有集群不会被外部部门租户访问，可以不开启。
:::
+
+## 1.权限控制特性介绍
+权限控制（ACL）主要为RocketMQ提供Topic资源级别的用户访问控制。用户在使用RocketMQ权限控制时，可以在Client客户端通过
RPCHook注入AccessKey和SecretKey签名；同时，将对应的权限控制属性（包括Topic访问权限、IP白名单和AccessKey和SecretKey签名等）设置在distribution/conf/plain_acl.yml的配置文件中。Broker端对AccessKey所拥有的权限进行校验，校验不过，抛出异常；
+ACL客户端可以参考：**org.apache.rocketmq.example.simple**包下面的**AclClient**代码。
+
## 2. 权限控制的定义与属性值
### 2.1权限定义
对RocketMQ的Topic资源访问权限控制定义主要如下表所示，分为以下四种
+
| 权限 | 含义 |
| --- | --- |
| DENY | 拒绝 |
