feat(tools.func): use distro packages for MariaDB by default (#11049)

- Changed setup_mariadb() to use Debian/Ubuntu distribution packages by default
- Official MariaDB repository only used when specific version is requested
- Added cleanup logic for old/orphaned repository files with apt update
- Added version comparison to prevent downgrades (keeps higher version installed)
- Added automatic fallback to distro packages if repo installation fails
- Extracted _setup_mariadb_runtime_dir() helper function
- Updated all related documentation

This change improves reliability by avoiding MariaDB mirror issues
(HTTPS->HTTP redirects, geographic availability problems) for standard
installations while still allowing specific versions when needed.

docs/install/DETAILED_GUIDE.md

@@ -544,7 +544,8 @@ network_check
 update_os
 
 PHP_VERSION="8.4" PHP_MODULE="bcmath,curl,pdo_mysql" setup_php
-MARIADB_VERSION="11.4" setup_mariadb
+setup_mariadb  # Uses distribution packages (recommended)
+# Or for specific version: MARIADB_VERSION="11.4" setup_mariadb
 
 # Database setup
 DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)

docs/install/README.md

@@ -85,7 +85,8 @@ pkg_install curl wget git
 ```bash
 setup_nodejs "20"
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages (recommended)
+# MARIADB_VERSION="11.4" setup_mariadb  # For specific version
 ```
 
 ### Phase 4: Application Download

docs/misc/tools.func/README.md

@@ -75,7 +75,8 @@ Complete reference of environment variables and configuration options.
 ```bash
 setup_nodejs "20"     # Install Node.js v20
 setup_php "8.2"       # Install PHP 8.2
-setup_mariadb "11"    # Install MariaDB 11
+setup_mariadb         # Install MariaDB (distribution packages)
+# MARIADB_VERSION="11.4" setup_mariadb  # Specific version from official repo
 ```
 
 ### Safe Package Operations

docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md

@@ -24,7 +24,7 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_golang(VERSION)` - Install Go programming language
 
 **Databases**:
-- `setup_mariadb(VERSION)` - Install MariaDB server
+- `setup_mariadb()` - Install MariaDB server (distro packages by default)
 - `setup_postgresql(VERSION)` - Install PostgreSQL
 - `setup_mongodb(VERSION)` - Install MongoDB
 - `setup_redis(VERSION)` - Install Redis cache
@@ -238,17 +238,20 @@ setup_php "8.3"
 
 ---
 
-### setup_mariadb(VERSION)
+### setup_mariadb()
 
 Install MariaDB server and client utilities.
 
 **Signature**:
 ```bash
-setup_mariadb VERSION
+setup_mariadb                         # Uses distribution packages (recommended)
+MARIADB_VERSION="11.4" setup_mariadb  # Uses official MariaDB repository
 ```
 
-**Parameters**:
-- `VERSION` - MariaDB version (e.g., "10.6", "11.0")
+**Variables**:
+- `MARIADB_VERSION` - (optional) Specific MariaDB version
+  - Not set or `"latest"`: Uses distribution packages (most reliable, avoids mirror issues)
+  - Specific version (e.g., `"11.4"`, `"12.2"`): Uses official MariaDB repository
 
 **Returns**:
 - `0` - Installation successful
@@ -259,7 +262,11 @@ setup_mariadb VERSION
 
 **Example**:
 ```bash
-setup_mariadb "11.0"
+# Recommended: Use distribution packages (stable, no mirror issues)
+setup_mariadb
+
+# Specific version from official repository
+MARIADB_VERSION="11.4" setup_mariadb
 ```
 
 ---
@@ -441,7 +448,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 
 pkg_update                    # Update package lists
 setup_nodejs "20"             # Install Node.js
-setup_mariadb "11"            # Install MariaDB
+setup_mariadb                 # Install MariaDB (distribution packages)
 
 # ... application installation ...
 
@@ -460,7 +467,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 pkg_update
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages
 setup_composer
 ```
 

docs/misc/tools.func/TOOLS_FUNC_USAGE_EXAMPLES.md

@@ -65,7 +65,7 @@ pkg_update
 
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages (recommended)
 setup_composer
 
 msg_ok "Web stack installed"
@@ -388,7 +388,7 @@ pkg_install package-name
 # Chain multiple tools together
 setup_nodejs "20"
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Distribution packages (recommended)
 
 # Check command success
 if ! setup_docker; then