perf(core): implement efficient bulk user deletion

Revamps the entire user deletion process to resolve critical performance bottlenecks that caused the web panel and database to freeze when removing multiple users.

- **Backend:** Core scripts (`kickuser.py`, `remove_user.py`) and the database layer are re-engineered to handle multiple users in a single, efficient batch operation using MongoDB's `delete_many`.
- **API:** A new `POST /api/v1/users/bulk-delete` endpoint is introduced for batch removals. The existing single-user `DELETE` endpoint is fixed to align with the new bulk logic.
- **Frontend:** The Users page now intelligently calls the bulk API when multiple users are selected, drastically improving UI responsiveness and reducing server load.

Author: ReturnFI

core/cli.py

@@ -184,23 +184,32 @@ def reset_user(username: str):
 
 
 @cli.command('remove-user')
-@click.option('--username', '-u', required=True, help='Username for the user to remove', type=str)
-def remove_user(username: str):
+@click.argument('usernames', nargs=-1, required=True)
+def remove_user(usernames: tuple[str]):
+    """Removes one or more users."""
+    if not usernames:
+        click.echo("No usernames provided.", err=True)
+        return
+        
     try:
-        cli_api.kick_user_by_name(username)
+        usernames_list = list(usernames)
+        cli_api.kick_users_by_name(usernames_list)
         cli_api.traffic_status(display_output=False)
-        cli_api.remove_user(username)
-        click.echo(f"User '{username}' removed successfully.")
+        cli_api.remove_users(usernames_list)
+        click.echo(f"Users '{', '.join(usernames)}' removed successfully.")
     except Exception as e:
         click.echo(f'{e}', err=True)
 
 @cli.command('kick-user')
-@click.option('--username', '-u', required=True, help='Username of the user to kick')
-def kick_user(username: str):
-    """Kicks a specific user by username."""
+@click.argument('usernames', nargs=-1, required=True)
+def kick_user(usernames: tuple[str]):
+    """Kicks one or more users by username."""
+    if not usernames:
+        click.echo("No usernames provided.", err=True)
+        return
+        
     try:
-        cli_api.kick_user_by_name(username)
-        # click.echo(f"User '{username}' kicked successfully.")
+        cli_api.kick_users_by_name(list(usernames))
     except Exception as e:
         click.echo(f'{e}', err=True)
 

core/cli_api.py

@@ -351,24 +351,26 @@ def reset_user(username: str):
     run_cmd(['python3', Command.RESET_USER.value, username])
 
 
-def remove_user(username: str):
+def remove_users(usernames: list[str]):
     '''
-    Removes a user by username.
+    Removes one or more users by username.
     '''
-    run_cmd(['python3', Command.REMOVE_USER.value, username])
+    if not usernames:
+        return
+    run_cmd(['python3', Command.REMOVE_USER.value, *usernames])
 
-def kick_user_by_name(username: str):
-    '''Kicks a specific user by username.'''
-    if not username:
-        raise InvalidInputError('Username must be provided to kick a specific user.')
+def kick_users_by_name(usernames: list[str]):
+    '''Kicks one or more users by username.'''
+    if not usernames:
+        raise InvalidInputError('Username(s) must be provided to kick.')
     script_path = Command.KICK_USER_SCRIPT.value
     if not os.path.exists(script_path):
         raise ScriptNotFoundError(f"Kick user script not found at: {script_path}")
     try:
-        subprocess.run(['python3', script_path, username], check=True)
+        subprocess.run(['python3', script_path, *usernames], check=True)
     except subprocess.CalledProcessError as e:
         raise CommandExecutionError(f"Failed to execute kick user script: {e}")
-
+        
 # TODO: it's better to return json
 def show_user_uri(username: str, qrcode: bool, ipv: int, all: bool, singbox: bool, normalsub: bool) -> str | None:
     '''

core/scripts/db/database.py

@@ -35,6 +35,9 @@ def update_user(self, username, updates):
     def delete_user(self, username):
         return self.collection.delete_one({"_id": username.lower()})
 
+    def delete_users(self, usernames):
+        return self.collection.delete_many({"_id": {"$in": usernames}})
+
 try:
     db = Database()
 except pymongo.errors.ConnectionFailure:

core/scripts/hysteria2/kickuser.py

@@ -36,15 +36,16 @@ def get_api_secret(config_path: str) -> str:
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Kick a Hysteria2 user via the API.",
-        usage="%(prog)s <username>" 
+        description="Kick one or more Hysteria2 users via the API.",
+        usage="%(prog)s <username1> [username2] ..."
     )
     parser.add_argument(
-        "username",
-        help="The username (Auth identity) to kick."
+        "usernames",
+        nargs='+',
+        help="The username(s) (Auth identity) to kick."
     )
     args = parser.parse_args()
-    username_to_kick = args.username
+    usernames_to_kick = args.usernames
 
     try:
         api_secret = get_api_secret(CONFIG_FILE)
@@ -56,16 +57,14 @@ def main():
             secret=api_secret
         )
 
-        client.kick_clients([username_to_kick])
-
-        # print(f"User '{username_to_kick}' kicked successfully.")
+        client.kick_clients(usernames_to_kick)
         sys.exit(0)
 
     except (FileNotFoundError, KeyError, ValueError, json.JSONDecodeError) as e:
         print(f"Configuration Error: {e}", file=sys.stderr)
         sys.exit(1)
     except Hysteria2Error as e:
-        print(f"API Error kicking user '{username_to_kick}': {e}", file=sys.stderr)
+        print(f"API Error kicking users: {e}", file=sys.stderr)
         sys.exit(1)
     except ConnectionError as e:
          print(f"Connection Error: Could not connect to API at {API_BASE_URL}. Is it running? Details: {e}", file=sys.stderr)

core/scripts/hysteria2/remove_user.py

@@ -5,27 +5,31 @@
 import os
 from db.database import db
 
-def remove_user(username):
+def remove_users(usernames):
     if db is None:
         return 1, "Error: Database connection failed. Please ensure MongoDB is running."
 
+    if not usernames:
+        return 1, "Error: No usernames provided for removal."
+
     try:
-        result = db.delete_user(username)
+        result = db.delete_users(usernames)
+        
         if result.deleted_count > 0:
-            return 0, f"User {username} removed successfully."
+            return 0, f"{result.deleted_count} user(s) removed successfully."
         else:
-            return 1, f"Error: User {username} not found."
+            return 1, "Error: No matching users found for removal."
 
     except Exception as e:
-        return 1, f"An error occurred while removing the user: {e}"
+        return 1, f"An error occurred while removing users: {e}"
 
 def main():
-    if len(sys.argv) != 2:
-        print(f"Usage: {sys.argv[0]} <username>")
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <username1> [username2] ...")
         sys.exit(1)
 
-    username = sys.argv[1].lower()
-    exit_code, message = remove_user(username)
+    usernames = [username.lower() for username in sys.argv[1:]]
+    exit_code, message = remove_users(usernames)
     print(message)
     sys.exit(exit_code)
 

core/scripts/webpanel/routers/api/v1/user.py

@@ -111,6 +111,19 @@ async def show_multiple_user_uris_api(request: UsernamesRequest):
         raise HTTPException(status_code=400, detail=f'Unexpected error: {str(e)}')
 
 
+@router.post('/bulk-delete', response_model=DetailResponse)
+async def bulk_remove_users_api(body: UsernamesRequest):
+    if not body.usernames:
+        raise HTTPException(status_code=400, detail="No usernames provided.")
+    try:
+        cli_api.kick_users_by_name(body.usernames)
+        cli_api.traffic_status(display_output=False)
+        cli_api.remove_users(body.usernames)
+        return DetailResponse(detail=f'Users have been removed.')
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f'Error: {str(e)}')
+
+
 @router.get('/{username}', response_model=UserInfoResponse)
 async def get_user_api(username: str):
     """
@@ -156,7 +169,7 @@ async def edit_user_api(username: str, body: EditUserInputBody):
         HTTPException: if an error occurs while editing the user.
     """
     try:
-        cli_api.kick_user_by_name(username)
+        cli_api.kick_users_by_name([username])
         cli_api.traffic_status(display_output=False)
         cli_api.edit_user(username, body.new_username, body.new_traffic_limit, body.new_expiration_days,
                           body.renew_password, body.renew_creation_date, body.blocked, body.unlimited_ip)
@@ -184,12 +197,11 @@ async def remove_user_api(username: str):
         if not user:
             raise HTTPException(status_code=404, detail=f'User {username} not found.')
 
-        cli_api.kick_user_by_name(username)
+        cli_api.kick_users_by_name([username])
         cli_api.traffic_status(display_output=False)
-        cli_api.remove_user(username)
+        cli_api.remove_users([username])
         return DetailResponse(detail=f'User {username} has been removed.')
     except HTTPException:
-
         raise
     except Exception as e:
         raise HTTPException(status_code=400, detail=f'Error: {str(e)}')

core/scripts/webpanel/templates/users.html

@@ -407,11 +407,26 @@ <h5 class="modal-title" id="showLinksModalLabel">Extract User Links</h5>
                 confirmButtonText: "Yes, delete them!",
             }).then((result) => {
                 if (!result.isConfirmed) return;
-                const urlTemplate = "{{ url_for('remove_user_api', username='U') }}";
-                const promises = selectedUsers.map(user => $.ajax({ url: urlTemplate.replace('U', user), method: "DELETE" }));
-                Promise.all(promises)
-                    .then(() => Swal.fire("Success!", "Selected users deleted.", "success").then(() => location.reload()))
-                    .catch(() => Swal.fire("Error!", "An error occurred while deleting users.", "error"));
+
+                if (selectedUsers.length > 1) {
+                    const bulkUrl = "{{ url_for('bulk_remove_users_api') }}";
+                    $.ajax({
+                        url: bulkUrl,
+                        method: "POST",
+                        contentType: "application/json",
+                        data: JSON.stringify({ usernames: selectedUsers })
+                    })
+                    .done(() => Swal.fire("Success!", "Selected users have been deleted.", "success").then(() => location.reload()))
+                    .fail((err) => Swal.fire("Error!", err.responseJSON?.detail || "An error occurred while deleting users.", "error"));
+                } else {
+                    const singleUrl = "{{ url_for('remove_user_api', username='U') }}".replace('U', selectedUsers[0]);
+                    $.ajax({
+                        url: singleUrl,
+                        method: "DELETE"
+                    })
+                    .done(() => Swal.fire("Success!", "The user has been deleted.", "success").then(() => location.reload()))
+                    .fail((err) => Swal.fire("Error!", err.responseJSON?.detail || "An error occurred while deleting the user.", "error"));
+                }
             });
         });