feat: optimized the stability of the web interface and basic Sparrow commands.（优化web界面和完善基础Sparrow指令的稳定性）

.work/extra/doc/2.USAGE_EN.md

@@ -182,20 +182,6 @@ Restart all services in the entire environment
 ./sparrow restart
 ```
 
-### (4) Web Dashboard
-
-If you need to manage and view sparrow services through a web interface, use the following command to start the web dashboard.
-
-```bash
-./sparrow web
-```
-
-You can also specify a port number (default 7979).
-
-```bash
-./sparrow web 8080
-```
-
 ### (5) Enter Container
 
 If you need to enter a running container for debugging or operations, you can use the enter command.
@@ -230,3 +216,32 @@ Specify the service name to enter the corresponding container:
 ```
 
 After entering the container, you will be logged in as the root user with the working directory set to `/`, and you can freely execute commands for debugging and operations.
+
+## 6. Visual Dashboard
+
+### (1) Start the Dashboard
+
+If you need to manage and view sparrow services through a web interface, use the following command to start the web dashboard.
+
+```bash
+./sparrow web
+```
+
+You can also specify a port number (default 7979).
+
+```bash
+./sparrow web 8080
+```
+
+### (2) Dashboard Features
+
+The visual dashboard provides a convenient web interface where you can complete all the following operations directly in your browser:
+
+- **Start/Stop Services**: Supports one-click start or stop of individual services, as well as batch operations
+- **View Service Status**: Real-time display of each service's running status, ports, logs, and other information
+- **Enter Containers**: Directly enter containers for debugging via the web terminal
+- **Image Management**: View, search, and pull images
+- **Repository Management**: Configure and manage image repositories
+- **Service Templates**: View and use service templates
+
+**Tip:** All command-line operations described in this document can be done more conveniently through the graphical interface in the visual dashboard. It is recommended to use the visual dashboard to familiarize yourself with sparrow's features when using it for the first time.

.work/extra/doc/2.USAGE_ZH.md

@@ -186,20 +186,6 @@ bash .work/test/run.sh
 ./sparrow restart
 ```
 
-### 4、工作后台
-
-如果需要通过网页形式管理和查看 sparrow 的服务，使用如下命令启动 web 后台
-
-```bash
-./sparrow web
-```
-
-也可以指定端口号（默认 7979）
-
-```bash
-./sparrow web 8080
-```
-
 ### 5、进入容器
 
 如果你需要进入运行中的容器进行调试或操作，可以使用 enter 命令。
@@ -234,3 +220,32 @@ bash .work/test/run.sh
 ```
 
 进入容器后，你将以 root 用户身份登录，工作目录为根目录 `/`，可以自由执行命令进行调试和操作。
+
+## 六、可视化后台
+
+### 1、启动后台
+
+如果需要通过网页形式管理和查看 sparrow 的服务，使用如下命令启动 web 后台
+
+```bash
+./sparrow web
+```
+
+也可以指定端口号（默认 7979）
+
+```bash
+./sparrow web 8080
+```
+
+### 2、后台功能
+
+可视化后台提供了便捷的 Web 界面，可以直接在浏览器中完成以下所有操作：
+
+- **启动/停止服务**：支持一键启动或停止单个服务，也可以批量操作
+- **查看服务状态**：实时显示各个服务的运行状态、端口、日志等信息
+- **进入容器**：通过 Web 终端直接进入容器进行调试操作
+- **镜像管理**：查看、搜索、拉取镜像
+- **仓库管理**：配置和管理镜像仓库
+- **服务模板**：查看和使用服务模板
+
+**提示：** 本文档中描述的所有命令行操作，都可以在可视化后台上通过图形界面更便捷地完成。推荐首次使用时通过可视化后台来熟悉 sparrow 的各项功能。

.work/include/internal/dockerhub.sh

@@ -24,11 +24,66 @@ search() {
         return 0
     fi
 
+    print_info "start search image in dockerhub for public: $1... "
+
     search_image=$1
-    remove_prefix_search_image=$(echo "$search_image" | sed 's/^docker.io\///')
-    echo "search search_image=${search_image}, remove_prefix_search_image=${remove_prefix_search_image}"
-    if docker search "$search_image" | grep -q "^$remove_prefix_search_image"; then
-        print_info "find it"
+
+    # parse image reference: [registry/]repo/image[:tag]
+    # remove docker.io prefix if present
+    image_without_registry=$(echo "$search_image" | sed 's/^docker.io\///')
+
+    # extract tag if exists
+    if echo "$image_without_registry" | grep -q ":"; then
+        tag=$(echo "$image_without_registry" | cut -d':' -f2)
+        image_name=$(echo "$image_without_registry" | cut -d':' -f1)
+        print_info "detected tag: $tag, image_name: $image_name"
+
+        # for Docker Hub, if image name doesn't have a user, add library/ prefix
+        if ! echo "$image_name" | grep -q "/"; then
+            image_name="library/$image_name"
+        fi
+
+        # check tag via Docker Registry API
+        print_info "checking tag existence via Docker Hub API... (if you seach tag, must use complete image name)"
+
+        # get auth token
+        token=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$image_name:pull" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
+
+        if [ -z "$token" ]; then
+            print_warn "failed to get auth token, falling back to docker search without tag"
+            # fall through to use docker search
+        else
+            # check manifest
+            http_code=$(curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $token" "https://registry-1.docker.io/v2/$image_name/manifests/$tag")
+
+            if [ "$http_code" = "200" ]; then
+                print_info "find it: $search_image (tag $tag exists)"
+                return 0
+            else
+                print_warn "not find it: $search_image (tag $tag does not exist, HTTP code: $http_code)"
+                return 1
+            fi
+        fi
+    fi
+
+    # no tag, use original docker search
+    remove_prefix_search_image=$(echo "$search_image" | sed 's/^docker.io\///' | cut -d':' -f1)
+    search_image_without_tag=$(echo "$search_image" | cut -d':' -f1)
+    print_info "search search_image=${search_image}, search_image_without_tag=${search_image_without_tag}, remove_prefix_search_image=${remove_prefix_search_image}"
+
+    # save and print the result of docker search
+    search_result=$(docker search "$search_image_without_tag")
+    print_info "docker search result:"
+    echo "$search_result" | while IFS= read -r line; do echo "  $line"; done
+
+    # print the grep result
+    print_info "grep pattern: $remove_prefix_search_image"
+
+    # check the match result (match anywhere in the line, not just start)
+    matched_lines=$(echo "$search_result" | grep "$remove_prefix_search_image")
+    if [ -n "$matched_lines" ]; then
+        print_info "find it, matched lines:"
+        echo "$matched_lines" | while IFS= read -r line; do echo "  $line"; done
         return 0  # find
     else
         print_warn "not find it"
@@ -46,13 +101,13 @@ pull() {
         exit 1
     fi
 
-    print_info "compute image..."
     image="sparrow-$1-$2"
     version="$3"
     local_image="$image:$version"
     remote_image="$DOCKERHUB_REPO/$image:$version"
+    print_info "pull image info: image=$image, version=$version, local_image=$local_image, remote_image=$remote_image"
 
-    search_image="$DOCKERHUB_REPO/$image"
+    search_image="$DOCKERHUB_REPO/$image:$version"
     print_info "search image: $search_image..."
     if ! search "$search_image"; then
         print_warn "no image: $search_image"
@@ -65,6 +120,9 @@ pull() {
         return 1
     fi
 
+    # 搜索的时候只能搜索到镜像名称，无法搜索到平台信息，所以只能通过docker pull的方式来验证平台是否匹配。
+    # When pulling with --platform, Docker may still pull an image if the manifest list includes a different architecture, but it will not match the requested platform. We need to verify the architecture after pulling to ensure we have the correct image.
+
     # Verify the pulled image actually matches the requested platform architecture.
     # docker pull --platform may succeed with a warning when the remote image only has a
     # different architecture (e.g. amd64 pulled when arm64 was requested).
@@ -74,6 +132,8 @@ pull() {
         print_warn "platform mismatch: expected ${expected_arch}, got ${actual_arch} for ${remote_image}. Removing and falling back to build."
         docker image rm "$remote_image" 2>/dev/null
         return 1
+    else
+        print_info "platform match: expected ${expected_arch}, got ${actual_arch} for ${remote_image}."
     fi
 
     print_info "tag image: $remote_image => $local_image..."

.work/include/internal/helper.sh

@@ -268,6 +268,7 @@ pull_or_build_app_image() {
         exit 1
     fi
     service="$1"
+    print_info "pull_or_build_app_image: service=$service"
 
     version_name=$(echo "IMAGE_APP_${service}_VERSION" | awk '{print toupper($0)}')
     version=$(eval echo "$"$version_name)