fix: skip invalid expose port (#2434)

* feat(olares-app): update version to v1.8.2

* feat(olares-app): update version to v1.8.2

.github/workflows/check.yaml

@@ -75,7 +75,7 @@ jobs:
     steps:
       - id: generate
         run: |
-          v=1.12.4-$(echo $RANDOM$RANDOM)
+          v=1.12.5-$(echo $RANDOM$RANDOM)
           echo "version=$v" >> "$GITHUB_OUTPUT"
 
   upload-cli:

.github/workflows/release-daily.yaml

@@ -17,7 +17,7 @@ jobs:
     steps:
       - id: generate
         run: |
-          v=1.12.4-$(date +"%Y%m%d")
+          v=1.12.5-$(date +"%Y%m%d")
           echo "version=$v" >> "$GITHUB_OUTPUT"
 
   release-id:

apps/.olares/config/user/helm-charts/system-apps/templates/olares-app.yaml

@@ -317,7 +317,7 @@ spec:
             chown -R 1000:1000 /uploadstemp && \
             chown -R 1000:1000 /appdata 
         - name: olares-app-init
-          image: beclab/system-frontend:v1.6.32
+          image: beclab/system-frontend:v1.8.2
           imagePullPolicy: IfNotPresent
           command:
             - /bin/sh
@@ -439,7 +439,7 @@ spec:
             - name: NATS_SUBJECT_VAULT
               value: os.vault.{{ .Values.bfl.username}}
         - name: user-service
-          image: beclab/user-service:v0.0.81
+          image: beclab/user-service:v0.0.82
           imagePullPolicy: IfNotPresent
           ports:
             - containerPort: 3000

apps/.olares/config/user/helm-charts/wizard/templates/wizard_deploy.yaml

@@ -29,7 +29,7 @@ spec:
 
       containers:
       - name: wizard
-        image: beclab/wizard:v1.6.30
+        image: beclab/wizard:v1.6.40
         imagePullPolicy: IfNotPresent
         ports:
         - containerPort: 80

build/base-package/install.sh

@@ -18,7 +18,7 @@ fi
 if [[ x"$VERSION" == x"" ]]; then
     if [[ "$LOCAL_RELEASE" == "1" ]]; then
         ts=$(date +%Y%m%d%H%M%S)
-        export VERSION="1.12.4-$ts"
+        export VERSION="1.12.5-$ts"
         echo "will build and use a local release of Olares with version: $VERSION"
         echo ""
     else
@@ -28,7 +28,7 @@ fi
 
 if [[ "x${VERSION}" == "x" || "x${VERSION:3}" == "xVERSION__" ]]; then
     echo "error: Olares version is unspecified, please set the VERSION env var and rerun this script."
-    echo "for example: VERSION=1.12.4-20241124 bash $0"
+    echo "for example: VERSION=1.12.5-20241124 bash $0"
     exit 1
 fi
 

build/base-package/joincluster.sh

@@ -158,7 +158,7 @@ export VERSION="#__VERSION__"
 
 if [[ "x${VERSION}" == "x" || "x${VERSION:3}" == "xVERSION__" ]]; then
     echo "error: Olares version is unspecified, please set the VERSION env var and rerun this script."
-    echo "for example: VERSION=1.12.4-20241124 bash $0"
+    echo "for example: VERSION=1.12.5-20241124 bash $0"
     exit 1
 fi
 

cli/cmd/ctl/amdgpu/install.go

@@ -0,0 +1,21 @@
+package amdgpu
+
+import (
+	"log"
+
+	"github.com/beclab/Olares/cli/pkg/pipelines"
+	"github.com/spf13/cobra"
+)
+
+func NewCmdAmdGpuInstall() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "install",
+		Short: "Install AMD ROCm stack via amdgpu-install",
+		Run: func(cmd *cobra.Command, args []string) {
+			if err := pipelines.AmdGpuInstall(); err != nil {
+				log.Fatalf("error: %v", err)
+			}
+		},
+	}
+	return cmd
+}

cli/cmd/ctl/amdgpu/root.go

@@ -0,0 +1,16 @@
+package amdgpu
+
+import "github.com/spf13/cobra"
+
+func NewCmdAmdGpu() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "amdgpu",
+		Short: "Manage AMD GPU ROCm stack",
+	}
+	cmd.AddCommand(NewCmdAmdGpuInstall())
+	cmd.AddCommand(NewCmdAmdGpuUninstall())
+	cmd.AddCommand(NewCmdAmdGpuStatus())
+	return cmd
+}
+
+

cli/cmd/ctl/amdgpu/status.go

@@ -0,0 +1,21 @@
+package amdgpu
+
+import (
+	"log"
+
+	"github.com/beclab/Olares/cli/pkg/pipelines"
+	"github.com/spf13/cobra"
+)
+
+func NewCmdAmdGpuStatus() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show AMD GPU driver and ROCm status",
+		Run: func(cmd *cobra.Command, args []string) {
+			if err := pipelines.AmdGpuStatus(); err != nil {
+				log.Fatalf("error: %v", err)
+			}
+		},
+	}
+	return cmd
+}

cli/cmd/ctl/amdgpu/uninstall.go

@@ -0,0 +1,21 @@
+package amdgpu
+
+import (
+	"log"
+
+	"github.com/beclab/Olares/cli/pkg/pipelines"
+	"github.com/spf13/cobra"
+)
+
+func NewCmdAmdGpuUninstall() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "uninstall",
+		Short: "Uninstall AMD ROCm stack via amdgpu-install",
+		Run: func(cmd *cobra.Command, args []string) {
+			if err := pipelines.AmdGpuUninstall(); err != nil {
+				log.Fatalf("error: %v", err)
+			}
+		},
+	}
+	return cmd
+}

cli/cmd/ctl/os/logs.go

@@ -3,6 +3,7 @@ package os
 import (
 	"archive/tar"
 	"compress/gzip"
+	"context"
 	"fmt"
 	"io"
 	"log"
@@ -13,6 +14,9 @@ import (
 	"strings"
 	"time"
 
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes"
 	"k8s.io/client-go/rest"
 	"k8s.io/client-go/tools/clientcmd"
 	ctrl "sigs.k8s.io/controller-runtime"
@@ -276,7 +280,7 @@ func collectSystemdLogs(tw *tar.Writer, options *LogCollectOptions) error {
 }
 
 func collectDmesgLogs(tw *tar.Writer, options *LogCollectOptions) error {
-	cmd := exec.Command("dmesg")
+	cmd := exec.Command("dmesg -T")
 	output, err := cmd.Output()
 	if err != nil {
 		return err
@@ -399,6 +403,126 @@ func collectKubernetesLogs(tw *tar.Writer, options *LogCollectOptions) error {
 		}
 	}
 
+	if err := collectNginxLogsFromLabeledPods(tw); err != nil {
+		if !options.IgnoreKubeErrors {
+			return fmt.Errorf("failed to collect nginx logs from labeled pods: %v", err)
+		}
+	}
+
+	return nil
+}
+
+func collectNginxLogsFromLabeledPods(tw *tar.Writer) error {
+	if _, err := util.GetCommand("kubectl"); err != nil {
+		fmt.Printf("warning: kubectl not found, skipping collecting nginx logs from labeled pods\n")
+		return nil
+	}
+
+	cfg, err := ctrl.GetConfig()
+	if err != nil {
+		return fmt.Errorf("failed to get kubeconfig: %v", err)
+	}
+	clientset, err := kubernetes.NewForConfig(cfg)
+	if err != nil {
+		return fmt.Errorf("failed to create kube client: %v", err)
+	}
+
+	type selectorSpec struct {
+		LabelSelector string
+		ContainerName string
+	}
+	selectors := []selectorSpec{
+		{LabelSelector: "app=l4-bfl-proxy", ContainerName: ""},
+		{LabelSelector: "tier=bfl", ContainerName: "ingress"},
+	}
+
+	type targetPod struct {
+		Namespace     string
+		Name          string
+		ContainerName string
+	}
+	var targets []targetPod
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	for _, sel := range selectors {
+		podList, err := clientset.CoreV1().Pods(corev1.NamespaceAll).List(ctx, metav1.ListOptions{LabelSelector: sel.LabelSelector})
+		if err != nil {
+			return fmt.Errorf("failed to list pods by label %q: %v", sel.LabelSelector, err)
+		}
+		for _, pod := range podList.Items {
+			targets = append(targets, targetPod{
+				Namespace:     pod.Namespace,
+				Name:          pod.Name,
+				ContainerName: sel.ContainerName,
+			})
+		}
+	}
+
+	if len(targets) == 0 {
+		return nil
+	}
+
+	// simplest approach: use kubectl cp (it already implements copy via tar over exec)
+	tempDir, err := os.MkdirTemp("", "olares-nginx-logs-*")
+	if err != nil {
+		return fmt.Errorf("failed to create temp directory for nginx logs: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	files := []string{"/var/log/nginx/access.log", "/var/log/nginx/error.log"}
+	for _, target := range targets {
+		for _, remotePath := range files {
+			base := filepath.Base(remotePath)
+			archivePath := filepath.Join("nginx", target.Namespace, target.Name, base)
+
+			dest := filepath.Join(tempDir, fmt.Sprintf("%s__%s__%s", target.Namespace, target.Name, base))
+
+			err := kubectlCopyFile(target.Namespace, target.Name, target.ContainerName, remotePath, dest)
+			if err != nil {
+				return fmt.Errorf("failed to kubectl cp %s/%s:%s: %v", target.Namespace, target.Name, remotePath, err)
+			}
+
+			fi, err := os.Stat(dest)
+			if err != nil {
+				return fmt.Errorf("failed to stat copied nginx log %s: %v", dest, err)
+			}
+
+			f, err := os.Open(dest)
+			if err != nil {
+				return fmt.Errorf("failed to open copied nginx log %s: %v", dest, err)
+			}
+			defer f.Close()
+
+			header := &tar.Header{
+				Name:    archivePath,
+				Mode:    0644,
+				Size:    fi.Size(),
+				ModTime: time.Now(),
+			}
+			if err := tw.WriteHeader(header); err != nil {
+				return fmt.Errorf("failed to write header for %s: %v", archivePath, err)
+			}
+			if _, err := io.CopyN(tw, f, header.Size); err != nil {
+				return fmt.Errorf("failed to write data for %s: %v", archivePath, err)
+			}
+		}
+	}
+	return nil
+}
+
+func kubectlCopyFile(namespace, pod, container, remotePath, destPath string) error {
+	args := []string{"-n", namespace, "cp"}
+	if container != "" {
+		args = append(args, "-c", container)
+	}
+	args = append(args, fmt.Sprintf("%s:%s", pod, remotePath), destPath)
+
+	cmd := exec.Command("kubectl", args...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("kubectl %s failed: %v, output: %s", strings.Join(args, " "), err, strings.TrimSpace(string(out)))
+	}
 	return nil
 }
 

cli/cmd/ctl/os/release.go

@@ -49,7 +49,7 @@ func NewCmdRelease() *cobra.Command {
 			}
 
 			if version == "" {
-				version = fmt.Sprintf("1.12.4-%s", time.Now().Format("20060102150405"))
+				version = fmt.Sprintf("1.12.5-%s", time.Now().Format("20060102150405"))
 				fmt.Printf("--version unspecified, using: %s\n", version)
 				time.Sleep(1 * time.Second)
 			}

cli/cmd/ctl/root.go

@@ -1,6 +1,7 @@
 package ctl
 
 import (
+	"github.com/beclab/Olares/cli/cmd/ctl/amdgpu"
 	"github.com/beclab/Olares/cli/cmd/ctl/disk"
 	"github.com/beclab/Olares/cli/cmd/ctl/gpu"
 	"github.com/beclab/Olares/cli/cmd/ctl/node"
@@ -33,6 +34,7 @@ func NewDefaultCommand() *cobra.Command {
 	cmds.AddCommand(os.NewOSCommands()...)
 	cmds.AddCommand(node.NewNodeCommand())
 	cmds.AddCommand(gpu.NewCmdGpu())
+	cmds.AddCommand(amdgpu.NewCmdAmdGpu())
 	cmds.AddCommand(user.NewUserCommand())
 	cmds.AddCommand(disk.NewDiskCommand())
 

cli/pkg/amdgpu/tasks.go

@@ -0,0 +1,133 @@
+package amdgpu
+
+import (
+	"fmt"
+	"os/exec"
+	"path"
+	"path/filepath"
+
+	"github.com/beclab/Olares/cli/pkg/common"
+	cc "github.com/beclab/Olares/cli/pkg/core/common"
+	"github.com/beclab/Olares/cli/pkg/core/connector"
+	"github.com/beclab/Olares/cli/pkg/core/logger"
+	"github.com/beclab/Olares/cli/pkg/core/task"
+	"github.com/beclab/Olares/cli/pkg/utils"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/pkg/errors"
+)
+
+// InstallAmdRocmModule installs AMD ROCm stack on supported Ubuntu if AMD GPU is present.
+type InstallAmdRocmModule struct {
+	common.KubeModule
+}
+
+func (m *InstallAmdRocmModule) Init() {
+	m.Name = "InstallAMDGPU"
+
+	installAmd := &task.RemoteTask{
+		Name:  "InstallAmdRocm",
+		Hosts: m.Runtime.GetHostsByRole(common.Master),
+		Action: &InstallAmdRocm{
+			// no manifest needed
+		},
+		Parallel: false,
+		Retry:    1,
+	}
+
+	m.Tasks = []task.Interface{
+		installAmd,
+	}
+}
+
+// InstallAmdRocm installs ROCm using amdgpu-install on Ubuntu 22.04/24.04 for AMD GPUs.
+type InstallAmdRocm struct {
+	common.KubeAction
+}
+
+func (t *InstallAmdRocm) Execute(runtime connector.Runtime) error {
+	si := runtime.GetSystemInfo()
+	if !si.IsLinux() || !si.IsUbuntu() || !(si.IsUbuntuVersionEqual(connector.Ubuntu2204) || si.IsUbuntuVersionEqual(connector.Ubuntu2404)) {
+		return nil
+	}
+
+	amdGPUExists, err := utils.HasAmdIGPU(runtime)
+	if err != nil {
+		return err
+	}
+	// skip rocm install
+	if !amdGPUExists {
+		return nil
+	}
+	rocmV, _ := utils.RocmVersion()
+	min := semver.MustParse("7.1.1")
+	if rocmV != nil && rocmV.LessThan(min) {
+		return fmt.Errorf("detected ROCm version %s, which is lower than required %s; please uninstall existing ROCm/AMDGPU components before installation with command: olares-cli amdgpu uninstall", rocmV.Original(), min.Original())
+	}
+	if rocmV != nil && rocmV.GreaterThan(min) {
+		logger.Warnf("Warning: detected ROCm version %s great than maximum tested version %s")
+		return nil
+	}
+	if rocmV != nil && rocmV.Equal(min) {
+		logger.Infof("detected ROCm version %s, skip rocm install...", min.Original())
+		return nil
+	}
+
+	// ensure python3-setuptools and python3-wheel
+	_, _ = runtime.GetRunner().SudoCmd("apt-get update", false, true)
+	checkPkgs := "dpkg -s python3-setuptools python3-wheel >/dev/null 2>&1 || DEBIAN_FRONTEND=noninteractive apt-get install -y python3-setuptools python3-wheel"
+	if _, err := runtime.GetRunner().SudoCmd(checkPkgs, false, true); err != nil {
+		return errors.Wrap(errors.WithStack(err), "failed to install python3-setuptools and python3-wheel")
+	}
+	// ensure amdgpu-install exists
+	if _, err := exec.LookPath("amdgpu-install"); err != nil {
+		var debURL string
+		if si.IsUbuntuVersionEqual(connector.Ubuntu2404) {
+			debURL = "https://repo.radeon.com/amdgpu-install/7.1.1/ubuntu/noble/amdgpu-install_7.1.1.70101-1_all.deb"
+		} else {
+			debURL = "https://repo.radeon.com/amdgpu-install/7.1.1/ubuntu/jammy/amdgpu-install_7.1.1.70101-1_all.deb"
+		}
+		tmpDeb := path.Join(runtime.GetBaseDir(), cc.PackageCacheDir, "gpu", "amdgpu-install_7.1.1.70101-1_all.deb")
+		if _, err := runtime.GetRunner().SudoCmd(fmt.Sprintf("install -d -m 0755 %s", filepath.Dir(tmpDeb)), false, true); err != nil {
+			return err
+		}
+		cmd := fmt.Sprintf("sh -c 'wget -O %s %s'", tmpDeb, debURL)
+		if _, err := runtime.GetRunner().SudoCmd(cmd, false, true); err != nil {
+			return errors.Wrap(errors.WithStack(err), "failed to download amdgpu-install deb")
+		}
+		if _, err := runtime.GetRunner().SudoCmd(fmt.Sprintf("DEBIAN_FRONTEND=noninteractive apt-get install -y %s", tmpDeb), false, true); err != nil {
+			return errors.Wrap(errors.WithStack(err), "failed to install amdgpu-install deb")
+		}
+	}
+	// run installer for rocm usecase
+	if _, err := runtime.GetRunner().SudoCmd("amdgpu-install -y --usecase=rocm", false, true); err != nil {
+		return errors.Wrap(errors.WithStack(err), "failed to install AMD ROCm via amdgpu-install")
+	}
+	fmt.Println()
+	logger.Warn("Warning: To enable ROCm, please reboot your machine after installation.")
+	return nil
+}
+
+type AmdgpuInstallAction struct {
+	common.KubeAction
+}
+
+func (t *AmdgpuInstallAction) Execute(runtime connector.Runtime) error {
+	if _, err := runtime.GetRunner().SudoCmd("amdgpu-install -y --usecase=rocm", false, true); err != nil {
+		return errors.Wrap(errors.WithStack(err), "failed to install AMD ROCm via amdgpu-install")
+	}
+	return nil
+}
+
+type AmdgpuUninstallAction struct {
+	common.KubeAction
+}
+
+func (t *AmdgpuUninstallAction) Execute(runtime connector.Runtime) error {
+	if _, err := runtime.GetRunner().SudoCmd("amdgpu-install --uninstall -y", false, true); err != nil {
+		return errors.Wrap(errors.WithStack(err), "failed to uninstall AMD ROCm via amdgpu-install")
+	}
+	fmt.Println()
+	logger.Warn("Warning: Please reboot your machine after uninstall to fully remove ROCm components.")
+	return nil
+}

cli/pkg/bootstrap/precheck/module.go

@@ -81,6 +81,7 @@ func (m *RunPrechecksModule) Init() {
 		new(NvidiaCardArchChecker),
 		new(NouveauChecker),
 		new(CudaChecker),
+		new(RocmChecker),
 	}
 	runPreChecks := &task.LocalTask{
 		Name: "RunPrechecks",

cli/pkg/bootstrap/precheck/tasks.go

@@ -372,6 +372,48 @@ func (c *CudaChecker) Check(runtime connector.Runtime) error {
 	return nil
 }
 
+// RocmChecker checks AMD ROCm version for AMD GPU on Ubuntu 22.04/24.04 only.
+type RocmChecker struct{}
+
+func (r *RocmChecker) Name() string {
+	return "ROCm"
+}
+
+func (r *RocmChecker) Check(runtime connector.Runtime) error {
+	if !runtime.GetSystemInfo().IsLinux() {
+		return nil
+	}
+	si := runtime.GetSystemInfo()
+	if !si.IsUbuntu() || !(si.IsUbuntuVersionEqual(connector.Ubuntu2204) || si.IsUbuntuVersionEqual(connector.Ubuntu2404)) {
+		return nil
+	}
+
+	// detect AMD GPU presence
+	amdGPUExists, err := utils.HasAmdIGPU(runtime)
+	if err != nil {
+		return err
+	}
+	// no AMD GPU found, no need to check rocm
+	if !amdGPUExists {
+		return nil
+	}
+
+	curV, err := utils.RocmVersion()
+	if err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	if os.IsNotExist(err) {
+		return nil
+	}
+
+	min := semver.MustParse("7.1.1")
+	if curV.LessThan(min) {
+		return fmt.Errorf("detected ROCm version %s, which is lower than required %s; please uninstall existing ROCm/AMDGPU components before installation with command: olares-cli amdgpu uninstall", curV.Original(), min.Original())
+	}
+	return nil
+}
+
 //////////////////////////////////////////////
 // precheck - task
 

cli/pkg/common/kube_runtime.go

@@ -287,7 +287,7 @@ func (a *Argument) LoadReleaseInfo() error {
 	return nil
 }
 
-func (a *Argument) SaveReleaseInfo() error {
+func (a *Argument) SaveReleaseInfo(withoutName bool) error {
 	if a.BaseDir == "" {
 		return errors.New("invalid: empty base directory")
 	}
@@ -300,15 +300,17 @@ func (a *Argument) SaveReleaseInfo() error {
 		ENV_OLARES_VERSION:  a.OlaresVersion,
 	}
 
-	if a.User != nil && a.User.UserName != "" && a.User.DomainName != "" {
-		releaseInfoMap["OLARES_NAME"] = fmt.Sprintf("%s@%s", a.User.UserName, a.User.DomainName)
-	} else {
-		if util.IsExist(OlaresReleaseFile) {
-			// if the user is not set, try to load the user name from the release file
-			envs, err := godotenv.Read(OlaresReleaseFile)
-			if err == nil {
-				if userName, ok := envs["OLARES_NAME"]; ok {
-					releaseInfoMap["OLARES_NAME"] = userName
+	if !withoutName {
+		if a.User != nil && a.User.UserName != "" && a.User.DomainName != "" {
+			releaseInfoMap["OLARES_NAME"] = fmt.Sprintf("%s@%s", a.User.UserName, a.User.DomainName)
+		} else {
+			if util.IsExist(OlaresReleaseFile) {
+				// if the user is not set, try to load the user name from the release file
+				envs, err := godotenv.Read(OlaresReleaseFile)
+				if err == nil {
+					if userName, ok := envs["OLARES_NAME"]; ok {
+						releaseInfoMap["OLARES_NAME"] = userName
+					}
 				}
 			}
 		}

cli/pkg/core/connector/system.go

@@ -51,10 +51,12 @@ func (d DebianVersion) String() string {
 }
 
 const (
-	Ubuntu20 UbuntuVersion = "20."
-	Ubuntu22 UbuntuVersion = "22."
-	Ubuntu24 UbuntuVersion = "24."
-	Ubuntu25 UbuntuVersion = "25."
+	Ubuntu20   UbuntuVersion = "20."
+	Ubuntu22   UbuntuVersion = "22."
+	Ubuntu24   UbuntuVersion = "24."
+	Ubuntu25   UbuntuVersion = "25."
+	Ubuntu2204 UbuntuVersion = "22.04"
+	Ubuntu2404 UbuntuVersion = "24.04"
 
 	Debian9  DebianVersion = "9"
 	Debian10 DebianVersion = "10"

cli/pkg/gpu/tasks.go

@@ -263,6 +263,10 @@ func (t *PatchK3sDriver) Execute(runtime connector.Runtime) error {
 		return err
 	}
 
+	if _, err := runtime.GetRunner().SudoCmd("apt install -y strace", false, false); err != nil {
+		return err
+	}
+
 	if _, err := runtime.GetRunner().SudoCmd(dstName, false, false); err != nil {
 		return errors.Wrap(err, "failed to apply CUDA patch for WSL")
 	}

cli/pkg/gpu/templates/k3sCudaFix.go

@@ -10,17 +10,39 @@ var (
 	K3sCudaFixValues = template.Must(template.New("cuda_lib_fix.sh").Parse(
 		dedent.Dedent(`#!/bin/bash
 sh_c="sh -c"
-real_driver=$($sh_c "find /usr/lib/wsl/drivers/ -name libcuda.so.1.1|head -1")
+real_driver=""
+real_nvml=""
+
+# Try to find the real driver path via strace
+real_driver_path=$($sh_c "strace -qq -e trace=openat /usr/lib/wsl/lib/nvidia-smi 2>&1|grep '/usr/lib/wsl/drivers'|grep libnvidia-ml.so.1|awk '{print \$2}'|sed 's/[\",]//g'|sed 's/libnvidia-ml.so.1//g'")
+if [[ x"$real_driver_path" != x"" ]]; then
+    real_driver="${real_driver_path}libcuda.so.1.1"
+    real_nvml="${real_driver_path}libnvidia-ml.so.1"
+else
+    driver_path=$($sh_c "strace -qq -e trace=openat /usr/lib/wsl/lib/nvidia-smi 2>&1|grep '/usr/lib/wsl/'|grep libnvidia-ml.so.1")
+    if [[ x"$driver_path" != x"" ]]; then
+        echo "already fixed cuda libs, exit now."
+        exit 0
+    fi
+fi
+
+if [[ x"$real_driver" == x"" ]]; then
+    real_driver=$($sh_c "find /usr/lib/wsl/drivers/ -name libcuda.so.1.1|head -1")
+    real_nvml=$($sh_c "find /usr/lib/wsl/drivers/ -name libnvidia-ml.so.1|head -1")
+fi
+
 if [[ x"$real_driver" != x"" ]]; then
-    $sh_c "ln -s /usr/lib/wsl/lib/libcuda* /usr/lib/x86_64-linux-gnu/"
     $sh_c "rm -f /usr/lib/x86_64-linux-gnu/libcuda.so"
     $sh_c "rm -f /usr/lib/x86_64-linux-gnu/libcuda.so.1"
     $sh_c "rm -f /usr/lib/x86_64-linux-gnu/libcuda.so.1.1"
+    $sh_c "rm -f /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.1"
     $sh_c "cp -f $real_driver /usr/lib/wsl/lib/libcuda.so"
     $sh_c "cp -f $real_driver /usr/lib/wsl/lib/libcuda.so.1"
     $sh_c "cp -f $real_driver /usr/lib/wsl/lib/libcuda.so.1.1"
-    $sh_c "ln -s $real_driver /usr/lib/x86_64-linux-gnu/libcuda.so.1"
-    $sh_c "ln -s $real_driver /usr/lib/x86_64-linux-gnu/libcuda.so.1.1"
+    $sh_c "cp -f $real_nvml /usr/lib/wsl/lib/libnvidia-ml.so.1"
+    $sh_c "cp -f $real_driver /usr/lib/x86_64-linux-gnu/"
+    $sh_c "cp -f $real_nvml /usr/lib/x86_64-linux-gnu/"
+    $sh_c "ln -s /usr/lib/x86_64-linux-gnu/libcuda.so.1.1 /usr/lib/x86_64-linux-gnu/libcuda.so.1"
     $sh_c "ln -s /usr/lib/x86_64-linux-gnu/libcuda.so.1 /usr/lib/x86_64-linux-gnu/libcuda.so"
 fi`),
 	))

cli/pkg/k3s/module.go

@@ -36,6 +36,7 @@ import (
 	"github.com/beclab/Olares/cli/pkg/k3s/templates"
 	"github.com/beclab/Olares/cli/pkg/manifest"
 	"github.com/beclab/Olares/cli/pkg/registry"
+	"github.com/beclab/Olares/cli/pkg/storage"
 )
 
 type InstallContainerModule struct {
@@ -470,6 +471,18 @@ func (j *JoinNodesModule) Init() {
 		Parallel: true,
 	}
 
+	createSharedLibDirForWorker := &task.RemoteTask{
+		Name:  "CreateSharedLibDir(k3s)",
+		Desc:  "Create shared lib directory on worker",
+		Hosts: j.Runtime.GetHostsByRole(common.Worker),
+		Prepare: &prepare.PrepareCollection{
+			&kubernetes.NodeInCluster{Not: true},
+			new(common.OnlyWorker),
+		},
+		Action:   new(storage.CreateSharedLibDir),
+		Parallel: true,
+	}
+
 	enableK3s := &task.RemoteTask{
 		Name:  "EnableK3sService",
 		Desc:  "Enable k3s service",
@@ -536,6 +549,7 @@ func (j *JoinNodesModule) Init() {
 		k3sService,
 		k3sEnv,
 		k3sRegistryConfig,
+		createSharedLibDirForWorker,
 		enableK3s,
 		copyKubeConfigForMaster,
 		syncKubeConfigToWorker,

cli/pkg/k3s/tasks.go

@@ -195,13 +195,13 @@ func (g *GenerateK3sService) Execute(runtime connector.Runtime) error {
 	defaultKubeletArs := map[string]string{
 		"kube-reserved":           "cpu=200m,memory=250Mi,ephemeral-storage=1Gi",
 		"system-reserved":         "cpu=200m,memory=250Mi,ephemeral-storage=1Gi",
-		"eviction-hard":           "memory.available<5%,nodefs.available<10%,imagefs.available<10%",
+		"eviction-hard":           "memory.available<5%,nodefs.available<5%,imagefs.available<5%",
 		"config":                  "/etc/rancher/k3s/kubelet.config",
 		"containerd":              container.DefaultContainerdCRISocket,
 		"cgroup-driver":           "systemd",
 		"runtime-request-timeout": "5m",
-		"image-gc-high-threshold": "91",
-		"image-gc-low-threshold":  "90",
+		"image-gc-high-threshold": "96",
+		"image-gc-low-threshold":  "95",
 		"housekeeping_interval":   "5s",
 	}
 	defaultKubeProxyArgs := map[string]string{
@@ -397,53 +397,23 @@ type CopyK3sKubeConfig struct {
 }
 
 func (c *CopyK3sKubeConfig) Execute(runtime connector.Runtime) error {
-	createConfigDirCmd := "mkdir -p /root/.kube && mkdir -p $HOME/.kube"
-	getKubeConfigCmd := "cp -f /etc/rancher/k3s/k3s.yaml /root/.kube/config"
-	chmodKubeConfigCmd := "chmod 0600 /root/.kube/config"
+	targetHome, targetUID, targetGID, err := utils.ResolveSudoUserHomeAndIDs(runtime)
+	if err != nil {
+		return err
+	}
 
-	cmd := strings.Join([]string{createConfigDirCmd, getKubeConfigCmd, chmodKubeConfigCmd}, " && ")
-	if _, err := runtime.GetRunner().SudoCmd(cmd, false, false); err != nil {
+	cmds := []string{
+		"mkdir -p /root/.kube",
+		"cp -f /etc/rancher/k3s/k3s.yaml /root/.kube/config",
+		"chmod 0600 /root/.kube/config",
+		fmt.Sprintf("mkdir -p %s", filepath.Join(targetHome, ".kube")),
+		fmt.Sprintf("cp -f /etc/rancher/k3s/k3s.yaml %s", filepath.Join(targetHome, ".kube", "config")),
+		fmt.Sprintf("chmod 0600 %s", filepath.Join(targetHome, ".kube", "config")),
+		fmt.Sprintf("chown -R %s:%s %s", targetUID, targetGID, filepath.Join(targetHome, ".kube")),
+	}
+	if _, err := runtime.GetRunner().SudoCmd(strings.Join(cmds, " && "), false, false); err != nil {
 		return errors.Wrap(errors.WithStack(err), "copy k3s kube config failed")
 	}
-
-	userMkdir := "mkdir -p $HOME/.kube"
-	if _, err := runtime.GetRunner().Cmd(userMkdir, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "user mkdir $HOME/.kube failed")
-	}
-
-	userCopyKubeConfig := "cp -f /etc/rancher/k3s/k3s.yaml $HOME/.kube/config"
-	if _, err := runtime.GetRunner().SudoCmd(userCopyKubeConfig, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "user copy /etc/rancher/k3s/k3s.yaml to $HOME/.kube/config failed")
-	}
-
-	if _, err := runtime.GetRunner().SudoCmd("chmod 0600 $HOME/.kube/config", false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "chmod k3s $HOME/.kube/config 0600 failed")
-	}
-
-	// userId, err := runtime.GetRunner().Cmd("echo $(id -u)", false, false)
-	// if err != nil {
-	// 	return errors.Wrap(errors.WithStack(err), "get user id failed")
-	// }
-
-	// userGroupId, err := runtime.GetRunner().Cmd("echo $(id -g)", false, false)
-	// if err != nil {
-	// 	return errors.Wrap(errors.WithStack(err), "get user group id failed")
-	// }
-
-	userId, err := runtime.GetRunner().Cmd("echo $SUDO_UID", false, false)
-	if err != nil {
-		return errors.Wrap(errors.WithStack(err), "get user id failed")
-	}
-
-	userGroupId, err := runtime.GetRunner().Cmd("echo $SUDO_GID", false, false)
-	if err != nil {
-		return errors.Wrap(errors.WithStack(err), "get user group id failed")
-	}
-
-	chownKubeConfig := fmt.Sprintf("chown -R %s:%s $HOME/.kube", userId, userGroupId)
-	if _, err := runtime.GetRunner().SudoCmd(chownKubeConfig, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "chown user kube config failed")
-	}
 	return nil
 }
 
@@ -493,59 +463,29 @@ func (s *SyncKubeConfigToWorker) Execute(runtime connector.Runtime) error {
 	if v, ok := s.PipelineCache.Get(common.ClusterStatus); ok {
 		cluster := v.(*K3sStatus)
 
-		createConfigDirCmd := "mkdir -p /root/.kube"
-		if _, err := runtime.GetRunner().SudoCmd(createConfigDirCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "create .kube dir failed")
-		}
-
 		oldServer := "server: https://127.0.0.1:6443"
 		newServer := fmt.Sprintf("server: https://%s:%d",
 			s.KubeConf.Cluster.ControlPlaneEndpoint.Domain,
 			s.KubeConf.Cluster.ControlPlaneEndpoint.Port)
 		newKubeConfig := strings.Replace(cluster.KubeConfig, oldServer, newServer, -1)
 
-		syncKubeConfigForRootCmd := fmt.Sprintf("echo '%s' > %s", newKubeConfig, "/root/.kube/config")
-		if _, err := runtime.GetRunner().SudoCmd(syncKubeConfigForRootCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "sync kube config for root failed")
-		}
-
-		if _, err := runtime.GetRunner().SudoCmd("chmod 0600 /root/.kube/config", false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "chmod k3s $HOME/.kube/config failed")
-		}
-
-		userConfigDirCmd := "mkdir -p $HOME/.kube"
-		if _, err := runtime.GetRunner().Cmd(userConfigDirCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "user mkdir $HOME/.kube failed")
-		}
-
-		syncKubeConfigForUserCmd := fmt.Sprintf("echo '%s' > %s", newKubeConfig, "$HOME/.kube/config")
-		if _, err := runtime.GetRunner().Cmd(syncKubeConfigForUserCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "sync kube config for normal user failed")
-		}
-
-		// userId, err := runtime.GetRunner().Cmd("echo $(id -u)", false, false)
-		// if err != nil {
-		// 	return errors.Wrap(errors.WithStack(err), "get user id failed")
-		// }
-
-		// userGroupId, err := runtime.GetRunner().Cmd("echo $(id -g)", false, false)
-		// if err != nil {
-		// 	return errors.Wrap(errors.WithStack(err), "get user group id failed")
-		// }
-
-		userId, err := runtime.GetRunner().Cmd("echo $SUDO_UID", false, false)
+		targetHome, targetUID, targetGID, err := utils.ResolveSudoUserHomeAndIDs(runtime)
 		if err != nil {
-			return errors.Wrap(errors.WithStack(err), "get user id failed")
+			return err
 		}
+		targetKubeConfigPath := filepath.Join(targetHome, ".kube", "config")
 
-		userGroupId, err := runtime.GetRunner().Cmd("echo $SUDO_GID", false, false)
-		if err != nil {
-			return errors.Wrap(errors.WithStack(err), "get user group id failed")
+		cmds := []string{
+			"mkdir -p /root/.kube",
+			fmt.Sprintf("echo '%s' > %s", newKubeConfig, "/root/.kube/config"),
+			"chmod 0600 /root/.kube/config",
+			fmt.Sprintf("mkdir -p %s", filepath.Join(targetHome, ".kube")),
+			fmt.Sprintf("echo '%s' > %s", newKubeConfig, targetKubeConfigPath),
+			fmt.Sprintf("chmod 0600 %s", targetKubeConfigPath),
+			fmt.Sprintf("chown -R %s:%s %s", targetUID, targetGID, filepath.Join(targetHome, ".kube")),
 		}
-
-		chownKubeConfig := fmt.Sprintf("chown -R %s:%s -R $HOME/.kube", userId, userGroupId)
-		if _, err := runtime.GetRunner().SudoCmd(chownKubeConfig, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "chown user kube config failed")
+		if _, err := runtime.GetRunner().SudoCmd(strings.Join(cmds, " && "), false, false); err != nil {
+			return errors.Wrap(errors.WithStack(err), "sync kube config failed")
 		}
 	}
 	return nil

cli/pkg/kubernetes/module.go

@@ -23,6 +23,7 @@ import (
 	"github.com/beclab/Olares/cli/pkg/core/prepare"
 	"github.com/beclab/Olares/cli/pkg/core/task"
 	"github.com/beclab/Olares/cli/pkg/manifest"
+	"github.com/beclab/Olares/cli/pkg/storage"
 )
 
 type StatusModule struct {
@@ -243,6 +244,18 @@ func (j *JoinNodesModule) Init() {
 		Retry:    5,
 	}
 
+	createSharedLibDirForWorker := &task.RemoteTask{
+		Name:  "CreateSharedLibDir(k8s)",
+		Desc:  "Create shared lib directory on worker",
+		Hosts: j.Runtime.GetHostsByRole(common.Worker),
+		Prepare: &prepare.PrepareCollection{
+			&NodeInCluster{Not: true},
+			new(common.OnlyWorker),
+		},
+		Action:   new(storage.CreateSharedLibDir),
+		Parallel: true,
+	}
+
 	joinWorkerNode := &task.RemoteTask{
 		Name:  "JoinWorkerNode(k8s)",
 		Desc:  "Join worker node",
@@ -323,6 +336,7 @@ func (j *JoinNodesModule) Init() {
 	j.Tasks = []task.Interface{
 		generateKubeadmConfig,
 		joinMasterNode,
+		createSharedLibDirForWorker,
 		joinWorkerNode,
 		copyKubeConfig,
 		removeMasterTaint,

cli/pkg/kubernetes/tasks.go

@@ -417,51 +417,23 @@ type CopyKubeConfigForControlPlane struct {
 }
 
 func (c *CopyKubeConfigForControlPlane) Execute(runtime connector.Runtime) error {
-	createConfigDirCmd := "mkdir -p /root/.kube"
-	getKubeConfigCmd := "cp -f /etc/kubernetes/admin.conf /root/.kube/config"
-	cmd := strings.Join([]string{createConfigDirCmd, getKubeConfigCmd}, " && ")
-	if _, err := runtime.GetRunner().SudoCmd(cmd, false, false); err != nil {
+	targetHome, targetUID, targetGID, err := utils.ResolveSudoUserHomeAndIDs(runtime)
+	if err != nil {
+		return err
+	}
+
+	cmds := []string{
+		"mkdir -p /root/.kube",
+		"cp -f /etc/kubernetes/admin.conf /root/.kube/config",
+		"chmod 0600 /root/.kube/config",
+		fmt.Sprintf("mkdir -p %s", filepath.Join(targetHome, ".kube")),
+		fmt.Sprintf("cp -f /etc/kubernetes/admin.conf %s", filepath.Join(targetHome, ".kube", "config")),
+		fmt.Sprintf("chmod 0600 %s", filepath.Join(targetHome, ".kube", "config")),
+		fmt.Sprintf("chown -R %s:%s %s", targetUID, targetGID, filepath.Join(targetHome, ".kube")),
+	}
+	if _, err := runtime.GetRunner().SudoCmd(strings.Join(cmds, " && "), false, false); err != nil {
 		return errors.Wrap(errors.WithStack(err), "copy kube config failed")
 	}
-
-	userMkdir := "mkdir -p $HOME/.kube"
-	if _, err := runtime.GetRunner().Cmd(userMkdir, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "user mkdir $HOME/.kube failed")
-	}
-
-	userCopyKubeConfig := "cp -f /etc/kubernetes/admin.conf $HOME/.kube/config"
-	if _, err := runtime.GetRunner().SudoCmd(userCopyKubeConfig, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "user copy /etc/kubernetes/admin.conf to $HOME/.kube/config failed")
-	}
-
-	if _, err := runtime.GetRunner().SudoCmd("chmod 0600 $HOME/.kube/config", false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "chmod $HOME/.kube/config failed")
-	}
-
-	// userId, err := runtime.GetRunner().Cmd("echo $(id -u)", false, false)
-	// if err != nil {
-	// 	return errors.Wrap(errors.WithStack(err), "get user id failed")
-	// }
-
-	// userGroupId, err := runtime.GetRunner().Cmd("echo $(id -g)", false, false)
-	// if err != nil {
-	// 	return errors.Wrap(errors.WithStack(err), "get user group id failed")
-	// }
-
-	userId, err := runtime.GetRunner().Cmd("echo $SUDO_UID", false, false)
-	if err != nil {
-		return errors.Wrap(errors.WithStack(err), "get user id failed")
-	}
-
-	userGroupId, err := runtime.GetRunner().Cmd("echo $SUDO_GID", false, false)
-	if err != nil {
-		return errors.Wrap(errors.WithStack(err), "get user group id failed")
-	}
-
-	chownKubeConfig := fmt.Sprintf("chown -R %s:%s $HOME/.kube", userId, userGroupId)
-	if _, err := runtime.GetRunner().SudoCmd(chownKubeConfig, false, false); err != nil {
-		return errors.Wrap(errors.WithStack(err), "chown user kube config failed")
-	}
 	return nil
 }
 
@@ -521,53 +493,23 @@ func (s *SyncKubeConfigToWorker) Execute(runtime connector.Runtime) error {
 	if v, ok := s.PipelineCache.Get(common.ClusterStatus); ok {
 		cluster := v.(*KubernetesStatus)
 
-		createConfigDirCmd := "mkdir -p /root/.kube"
-		if _, err := runtime.GetRunner().SudoCmd(createConfigDirCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "create .kube dir failed")
-		}
-
-		syncKubeConfigForRootCmd := fmt.Sprintf("echo '%s' > %s", cluster.KubeConfig, "/root/.kube/config")
-		if _, err := runtime.GetRunner().SudoCmd(syncKubeConfigForRootCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "sync kube config for root failed")
-		}
-
-		if _, err := runtime.GetRunner().SudoCmd("chmod 0600 /root/.kube/config", false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "chmod $HOME/.kube/config failed")
-		}
-
-		userConfigDirCmd := "mkdir -p $HOME/.kube"
-		if _, err := runtime.GetRunner().Cmd(userConfigDirCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "user mkdir $HOME/.kube failed")
-		}
-
-		syncKubeConfigForUserCmd := fmt.Sprintf("echo '%s' > %s", cluster.KubeConfig, "$HOME/.kube/config")
-		if _, err := runtime.GetRunner().Cmd(syncKubeConfigForUserCmd, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "sync kube config for normal user failed")
-		}
-
-		// userId, err := runtime.GetRunner().Cmd("echo $(id -u)", false, false)
-		// if err != nil {
-		// 	return errors.Wrap(errors.WithStack(err), "get user id failed")
-		// }
-
-		// userGroupId, err := runtime.GetRunner().Cmd("echo $(id -g)", false, false)
-		// if err != nil {
-		// 	return errors.Wrap(errors.WithStack(err), "get user group id failed")
-		// }
-
-		userId, err := runtime.GetRunner().Cmd("echo $SUDO_UID", false, false)
+		targetHome, targetUID, targetGID, err := utils.ResolveSudoUserHomeAndIDs(runtime)
 		if err != nil {
-			return errors.Wrap(errors.WithStack(err), "get user id failed")
+			return err
 		}
+		targetKubeConfigPath := filepath.Join(targetHome, ".kube", "config")
 
-		userGroupId, err := runtime.GetRunner().Cmd("echo $SUDO_GID", false, false)
-		if err != nil {
-			return errors.Wrap(errors.WithStack(err), "get user group id failed")
+		cmds := []string{
+			"mkdir -p /root/.kube",
+			fmt.Sprintf("echo '%s' > %s", cluster.KubeConfig, "/root/.kube/config"),
+			"chmod 0600 /root/.kube/config",
+			fmt.Sprintf("mkdir -p %s", filepath.Join(targetHome, ".kube")),
+			fmt.Sprintf("echo '%s' > %s", cluster.KubeConfig, targetKubeConfigPath),
+			fmt.Sprintf("chmod 0600 %s", targetKubeConfigPath),
+			fmt.Sprintf("chown -R %s:%s %s", targetUID, targetGID, filepath.Join(targetHome, ".kube")),
 		}
-
-		chownKubeConfig := fmt.Sprintf("chown -R %s:%s -R $HOME/.kube", userId, userGroupId)
-		if _, err := runtime.GetRunner().SudoCmd(chownKubeConfig, false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "chown user kube config failed")
+		if _, err := runtime.GetRunner().SudoCmd(strings.Join(cmds, " && "), false, false); err != nil {
+			return errors.Wrap(errors.WithStack(err), "sync kube config failed")
 		}
 	}
 	return nil

cli/pkg/kubernetes/templates/v1beta2/kubeadm_config.go

@@ -296,8 +296,10 @@ func GetKubeletConfiguration(runtime connector.Runtime, kubeConf *common.KubeCon
 			"memory": "250Mi",
 		},
 		"evictionHard": map[string]string{
-			"memory.available": "5%",
-			"pid.available":    "10%",
+			"memory.available":  "5%",
+			"pid.available":     "10%",
+			"nodefs.available":  "5%",
+			"imagefs.available": "5%",
 		},
 		"evictionSoft": map[string]string{
 			"memory.available": "10%",
@@ -309,8 +311,8 @@ func GetKubeletConfiguration(runtime connector.Runtime, kubeConf *common.KubeCon
 		"evictionPressureTransitionPeriod": "30s",
 		"featureGates":                     FeatureGatesDefaultConfiguration,
 		"runtimeRequestTimeout":            "5m",
-		"imageGCHighThresholdPercent":      91,
-		"imageGCLowThresholdPercent":       90,
+		"imageGCHighThresholdPercent":      96,
+		"imageGCLowThresholdPercent":       95,
 	}
 
 	if securityEnhancement {

cli/pkg/phase/cluster/delete_cluster.go

@@ -111,6 +111,7 @@ func (p *phaseBuilder) phaseInstall() *phaseBuilder {
 				PhaseFile: common.TerminusStateFileInstalled,
 				BaseDir:   p.runtime.GetBaseDir(),
 			},
+			&terminus.WriteReleaseFileModule{WithoutName: true},
 		)
 	}
 	return p

cli/pkg/phase/system/linux.go

@@ -3,8 +3,7 @@ package system
 import (
 	"strings"
 
-	"github.com/beclab/Olares/cli/pkg/gpu"
-
+	"github.com/beclab/Olares/cli/pkg/amdgpu"
 	"github.com/beclab/Olares/cli/pkg/bootstrap/os"
 	"github.com/beclab/Olares/cli/pkg/bootstrap/patch"
 	"github.com/beclab/Olares/cli/pkg/bootstrap/precheck"
@@ -12,6 +11,7 @@ import (
 	"github.com/beclab/Olares/cli/pkg/container"
 	"github.com/beclab/Olares/cli/pkg/core/module"
 	"github.com/beclab/Olares/cli/pkg/daemon"
+	"github.com/beclab/Olares/cli/pkg/gpu"
 	"github.com/beclab/Olares/cli/pkg/images"
 	"github.com/beclab/Olares/cli/pkg/k3s"
 	"github.com/beclab/Olares/cli/pkg/manifest"
@@ -82,6 +82,7 @@ func (l *linuxPhaseBuilder) build() []module.Module {
 		addModule(&terminus.WriteReleaseFileModule{}).
 		addModule(gpuModuleBuilder(func() []module.Module {
 			return []module.Module{
+				&amdgpu.InstallAmdRocmModule{},
 				&gpu.InstallDriversModule{
 					ManifestModule: manifest.ManifestModule{
 						Manifest: l.manifestMap,

cli/pkg/pipelines/amdgpu.go

@@ -0,0 +1,101 @@
+package pipelines
+
+import (
+	"strings"
+
+	"github.com/beclab/Olares/cli/pkg/amdgpu"
+	"github.com/beclab/Olares/cli/pkg/common"
+	"github.com/beclab/Olares/cli/pkg/core/action"
+	"github.com/beclab/Olares/cli/pkg/core/connector"
+	"github.com/beclab/Olares/cli/pkg/core/logger"
+	"github.com/beclab/Olares/cli/pkg/core/module"
+	"github.com/beclab/Olares/cli/pkg/core/pipeline"
+	"github.com/beclab/Olares/cli/pkg/core/task"
+)
+
+type singleTaskModule struct {
+	common.KubeModule
+	name string
+	act  action.Action
+}
+
+func (m *singleTaskModule) Init() {
+	m.Name = m.name
+	m.Tasks = []task.Interface{
+		&task.LocalTask{
+			Name:   m.name,
+			Action: m.act,
+		},
+	}
+}
+
+func AmdGpuInstall() error {
+	arg := common.NewArgument()
+	arg.SetConsoleLog("amdgpuinstall.log", true)
+	runtime, err := common.NewKubeRuntime(common.AllInOne, *arg)
+	if err != nil {
+		return err
+	}
+	p := &pipeline.Pipeline{
+		Name:    "InstallAMDGPUDrivers",
+		Runtime: runtime,
+		Modules: []module.Module{
+			&amdgpu.InstallAmdRocmModule{},
+		},
+	}
+	return p.Start()
+}
+
+func AmdGpuUninstall() error {
+	arg := common.NewArgument()
+	arg.SetConsoleLog("amdgpuuninstall.log", true)
+	runtime, err := common.NewKubeRuntime(common.AllInOne, *arg)
+	if err != nil {
+		return err
+	}
+	p := &pipeline.Pipeline{
+		Name:    "UninstallAMDGPUDrivers",
+		Runtime: runtime,
+		Modules: []module.Module{
+			&singleTaskModule{name: "AmdgpuUninstall", act: new(amdgpu.AmdgpuUninstallAction)},
+		},
+	}
+	return p.Start()
+}
+
+func AmdGpuStatus() error {
+	arg := common.NewArgument()
+	runtime, err := common.NewKubeRuntime(common.AllInOne, *arg)
+	if err != nil {
+		return err
+	}
+	runtime.SetRunner(
+		&connector.Runner{
+			Host: &connector.BaseHost{
+				Name: common.LocalHost,
+				Arch: runtime.GetSystemInfo().GetOsArch(),
+				Os:   runtime.GetSystemInfo().GetOsType(),
+			},
+		},
+	)
+	amdModel, _ := runtime.GetRunner().SudoCmd("lspci | grep -iE 'VGA|3D|Display' | grep -iE 'AMD|ATI' | head -1 || true", false, false)
+	drvVer, _ := runtime.GetRunner().SudoCmd("modinfo amdgpu 2>/dev/null | awk -F': ' '/^version:/{print $2}' || true", false, false)
+	rocmVer, _ := runtime.GetRunner().SudoCmd("cat /opt/rocm/.info/version 2>/dev/null || true", false, false)
+
+	if strings.TrimSpace(amdModel) != "" {
+		logger.Infof("AMD GPU: %s", strings.TrimSpace(amdModel))
+	} else {
+		logger.Info("AMD GPU: not detected")
+	}
+	if strings.TrimSpace(drvVer) != "" {
+		logger.Infof("AMDGPU driver %s", strings.TrimSpace(drvVer))
+	} else {
+		logger.Info("AMDGPU driver version: unknown")
+	}
+	if strings.TrimSpace(rocmVer) != "" {
+		logger.Infof("ROCm version: %s", strings.TrimSpace(rocmVer))
+	} else {
+		logger.Info("ROCm version: not installed")
+	}
+	return nil
+}

cli/pkg/storage/tasks.go

@@ -396,3 +396,17 @@ func (t *DeleteTerminusData) Execute(runtime connector.Runtime) error {
 
 	return nil
 }
+
+type CreateSharedLibDir struct {
+	common.KubeAction
+}
+
+func (t *CreateSharedLibDir) Execute(runtime connector.Runtime) error {
+	if runtime.GetSystemInfo().IsDarwin() {
+		return nil
+	}
+	if _, err := runtime.GetRunner().SudoCmd(fmt.Sprintf("mkdir -p %s && chown 1000:1000 %s", OlaresSharedLibDir, OlaresSharedLibDir), false, false); err != nil {
+		return errors.Wrap(errors.WithStack(err), "failed to create shared lib dir")
+	}
+	return nil
+}

cli/pkg/terminus/modules.go

@@ -74,6 +74,7 @@ func (m *PreparedModule) Init() {
 
 type WriteReleaseFileModule struct {
 	common.KubeModule
+	WithoutName bool
 }
 
 func (m *WriteReleaseFileModule) Init() {
@@ -82,7 +83,7 @@ func (m *WriteReleaseFileModule) Init() {
 	m.Tasks = []task.Interface{
 		&task.LocalTask{
 			Name:   "WriteReleaseFile",
-			Action: new(WriteReleaseFile),
+			Action: &WriteReleaseFile{WithoutName: m.WithoutName},
 		},
 	}
 }

cli/pkg/terminus/ossystem.go

@@ -38,12 +38,6 @@ type InstallOsSystem struct {
 }
 
 func (t *InstallOsSystem) Execute(runtime connector.Runtime) error {
-	if !runtime.GetSystemInfo().IsDarwin() {
-		if _, err := runtime.GetRunner().SudoCmd(fmt.Sprintf("mkdir -p %s && chown 1000:1000 %s", storage.OlaresSharedLibDir, storage.OlaresSharedLibDir), false, false); err != nil {
-			return errors.Wrap(errors.WithStack(err), "failed to create shared lib dir")
-		}
-	}
-
 	config, err := ctrl.GetConfig()
 	if err != nil {
 		return err
@@ -367,6 +361,11 @@ func (m *InstallOsSystemModule) Init() {
 		Action: &CreateUserEnvConfigMap{},
 	}
 
+	createSharedLibDir := &task.LocalTask{
+		Name:   "CreateSharedLibDir",
+		Action: &storage.CreateSharedLibDir{},
+	}
+
 	installOsSystem := &task.LocalTask{
 		Name:   "InstallOsSystem",
 		Action: &InstallOsSystem{},
@@ -399,6 +398,7 @@ func (m *InstallOsSystemModule) Init() {
 	m.Tasks = []task.Interface{
 		applySystemEnv,
 		createUserEnvConfigMap,
+		createSharedLibDir,
 		installOsSystem,
 		createBackupConfigMap,
 		checkSystemService,

cli/pkg/terminus/tasks.go

@@ -97,25 +97,8 @@ func (t *CheckKeyPodsRunning) Execute(runtime connector.Runtime) error {
 		if !strings.HasPrefix(pod.Namespace, "user-") && !strings.HasPrefix(pod.Namespace, "os-") {
 			continue
 		}
-		if pod.Status.Phase != corev1.PodRunning {
-			return fmt.Errorf("pod %s/%s is not running", pod.Namespace, pod.Name)
-		}
-		if len(pod.Status.ContainerStatuses) != len(pod.Spec.Containers) {
-			return fmt.Errorf("pod %s/%s has not started all containers yet", pod.Namespace, pod.Name)
-		}
-		for _, cStatus := range pod.Status.ContainerStatuses {
-			if cStatus.State.Terminated != nil {
-				if cStatus.State.Terminated.ExitCode != 0 {
-					return fmt.Errorf("container %s in pod %s/%s is terminated", cStatus.Name, pod.Namespace, pod.Name)
-				}
-				continue
-			}
-			if cStatus.State.Running == nil {
-				return fmt.Errorf("container %s in pod %s/%s is not running", cStatus.Name, pod.Namespace, pod.Name)
-			}
-			if !cStatus.Ready {
-				return fmt.Errorf("container %s in pod %s/%s is not ready", cStatus.Name, pod.Namespace, pod.Name)
-			}
+		if err := utils.AssertPodReady(&pod); err != nil {
+			return err
 		}
 	}
 	return nil
@@ -126,29 +109,39 @@ type CheckPodsRunning struct {
 	labels map[string][]string
 }
 
-func (c *CheckPodsRunning) Execute(runtime connector.Runtime) error {
+func (c *CheckPodsRunning) Execute(_ connector.Runtime) error {
 	if c.labels == nil {
 		return nil
 	}
 
-	kubectl, err := util.GetCommand(common.CommandKubectl)
-	if err != nil {
-		return errors.Wrap(errors.WithStack(err), "kubectl not found")
-	}
-
 	var ctx, cancel = context.WithTimeout(context.Background(), 3*time.Minute)
 	defer cancel()
+
+	kubeConfig, err := ctrl.GetConfig()
+	if err != nil {
+		return errors.Wrap(err, "failed to load kubeconfig")
+	}
+	kubeClient, err := kubernetes.NewForConfig(kubeConfig)
+	if err != nil {
+		return errors.Wrap(err, "failed to create kube client")
+	}
+
 	for ns, labels := range c.labels {
 		for _, label := range labels {
-			var cmd = fmt.Sprintf("%s get pod -n %s -l '%s' -o jsonpath='{.items[*].status.phase}'", kubectl, ns, label)
-			phase, err := runtime.GetRunner().SudoCmdContext(ctx, cmd, false, false)
+			podList, err := kubeClient.CoreV1().Pods(ns).List(ctx, metav1.ListOptions{LabelSelector: label})
 			if err != nil {
 				return fmt.Errorf("pod status invalid, namespace: %s, label: %s, waiting ...", ns, label)
 			}
 
-			if phase != "Running" {
-				logger.Infof("pod in namespace: %s, label: %s, current phase: %s, waiting ...", ns, label, phase)
-				return fmt.Errorf("pod is %s, namespace: %s, label: %s, waiting ...", phase, ns, label)
+			if podList == nil || len(podList.Items) == 0 {
+				return fmt.Errorf("no pod found, namespace: %s, label: %s, waiting ...", ns, label)
+			}
+
+			for i := range podList.Items {
+				pod := &podList.Items[i]
+				if err := utils.AssertPodReady(pod); err != nil {
+					return err
+				}
 			}
 		}
 	}
@@ -250,13 +243,14 @@ func (t *PrepareFinished) Execute(runtime connector.Runtime) error {
 
 type WriteReleaseFile struct {
 	common.KubeAction
+	WithoutName bool
 }
 
 func (t *WriteReleaseFile) Execute(runtime connector.Runtime) error {
 	if util.IsExist(common.OlaresReleaseFile) {
 		logger.Debugf("found existing release file: %s, overriding ...", common.OlaresReleaseFile)
 	}
-	return t.KubeConf.Arg.SaveReleaseInfo()
+	return t.KubeConf.Arg.SaveReleaseInfo(t.WithoutName)
 }
 
 type RemoveReleaseFile struct {

cli/pkg/terminus/welcome.go

@@ -9,6 +9,7 @@ import (
 	"github.com/beclab/Olares/cli/pkg/core/connector"
 	"github.com/beclab/Olares/cli/pkg/core/logger"
 	"github.com/beclab/Olares/cli/pkg/core/task"
+	"github.com/beclab/Olares/cli/pkg/utils"
 )
 
 type WelcomeMessage struct {
@@ -68,6 +69,15 @@ func (t *WelcomeMessage) Execute(runtime connector.Runtime) error {
 	logger.Infof("Username: %s", t.KubeConf.Arg.User.UserName)
 	logger.Infof("Password: %s", t.KubeConf.Arg.User.Password)
 	fmt.Printf("\n------------------------------------------------\n\n\n\n\n")
+	fmt.Println()
+
+	// If AMD GPU on Ubuntu 22.04/24.04, print warning about reboot for ROCm
+	if si := runtime.GetSystemInfo(); si.IsUbuntu() && (si.IsUbuntuVersionEqual(connector.Ubuntu2204) || si.IsUbuntuVersionEqual(connector.Ubuntu2404)) {
+		if hasAmd, _ := utils.HasAmdIGPU(runtime); hasAmd {
+			logger.Warnf("\x1b[31mWarning: To enable ROCm, please reboot your machine after activation.\x1b[0m")
+			fmt.Println()
+		}
+	}
 
 	return nil
 }

cli/pkg/upgrade/1_12_4.go

@@ -8,36 +8,36 @@ import (
 	"github.com/beclab/Olares/cli/version"
 )
 
-var version_1_12_3 = semver.MustParse("1.12.3")
+var version_1_12_4 = semver.MustParse("1.12.4")
 
-type upgrader_1_12_3 struct {
+type upgrader_1_12_4 struct {
 	breakingUpgraderBase
 }
 
-func (u upgrader_1_12_3) Version() *semver.Version {
+func (u upgrader_1_12_4) Version() *semver.Version {
 	cliVersion, err := semver.NewVersion(version.VERSION)
 	// tolerate local dev version
 	if err != nil {
-		return version_1_12_3
+		return version_1_12_4
 	}
-	if samePatchLevelVersion(version_1_12_3, cliVersion) && getReleaseLineOfVersion(cliVersion) == mainLine {
+	if samePatchLevelVersion(version_1_12_4, cliVersion) && getReleaseLineOfVersion(cliVersion) == mainLine {
 		return cliVersion
 	}
-	return version_1_12_3
+	return version_1_12_4
 }
 
-func (u upgrader_1_12_3) AddedBreakingChange() bool {
-	if u.Version().Equal(version_1_12_3) {
+func (u upgrader_1_12_4) AddedBreakingChange() bool {
+	if u.Version().Equal(version_1_12_4) {
 		return true
 	}
 	return false
 }
 
-func (u upgrader_1_12_3) NeedRestart() bool {
+func (u upgrader_1_12_4) NeedRestart() bool {
 	return true
 }
 
-func (u upgrader_1_12_3) PrepareForUpgrade() []task.Interface {
+func (u upgrader_1_12_4) PrepareForUpgrade() []task.Interface {
 	tasks := make([]task.Interface, 0)
 
 	tasks = append(tasks, upgradeKsConfig()...)
@@ -57,7 +57,7 @@ func (u upgrader_1_12_3) PrepareForUpgrade() []task.Interface {
 	return tasks
 }
 
-func (u upgrader_1_12_3) UpgradeSystemComponents() []task.Interface {
+func (u upgrader_1_12_4) UpgradeSystemComponents() []task.Interface {
 	pre := []task.Interface{
 		&task.LocalTask{
 			Name:   "UpgradeL4BFLProxy",
@@ -69,7 +69,7 @@ func (u upgrader_1_12_3) UpgradeSystemComponents() []task.Interface {
 	return append(pre, u.upgraderBase.UpgradeSystemComponents()...)
 }
 
-func (u upgrader_1_12_3) UpdateOlaresVersion() []task.Interface {
+func (u upgrader_1_12_4) UpdateOlaresVersion() []task.Interface {
 	var tasks []task.Interface
 	tasks = append(tasks,
 		&task.LocalTask{
@@ -88,5 +88,5 @@ func (u upgrader_1_12_3) UpdateOlaresVersion() []task.Interface {
 }
 
 func init() {
-	registerMainUpgrader(upgrader_1_12_3{})
+	registerMainUpgrader(upgrader_1_12_4{})
 }

cli/pkg/utils/amdgpu.go

@@ -0,0 +1,67 @@
+package utils
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/Masterminds/semver/v3"
+	"github.com/beclab/Olares/cli/pkg/core/connector"
+)
+
+func HasAmdIGPU(execRuntime connector.Runtime) (bool, error) {
+	// Detect by CPU model names that bundle AMD AI NPU/graphics
+	targets := []string{
+		"AMD Ryzen AI Max+ 395",
+		"AMD Ryzen AI Max 390",
+		"AMD Ryzen AI Max 385",
+		"AMD Ryzen AI 9 HX 375",
+		"AMD Ryzen AI 9 HX 370",
+		"AMD Ryzen AI 9 365",
+	}
+	// try lscpu first: extract 'Model name' field
+	out, err := execRuntime.GetRunner().SudoCmd("lscpu 2>/dev/null | awk -F': *' '/^Model name/{print $2; exit}' || true", false, false)
+	if err != nil {
+		return false, err
+	}
+	if out != "" {
+		lo := strings.ToLower(strings.TrimSpace(out))
+		for _, t := range targets {
+			if strings.Contains(lo, strings.ToLower(t)) {
+				return true, nil
+			}
+		}
+	}
+	// fallback to /proc/cpuinfo
+	out, err = execRuntime.GetRunner().SudoCmd("awk -F': *' '/^model name/{print $2; exit}' /proc/cpuinfo 2>/dev/null || true", false, false)
+	if err != nil {
+		return false, err
+	}
+	if out != "" {
+		lo := strings.ToLower(strings.TrimSpace(out))
+		for _, t := range targets {
+			if strings.Contains(lo, strings.ToLower(t)) {
+				return true, nil
+			}
+		}
+	}
+	return false, nil
+}
+
+func RocmVersion() (*semver.Version, error) {
+	const rocmVersionFile = "/opt/rocm/.info/version"
+	data, err := os.ReadFile(rocmVersionFile)
+	if err != nil {
+		// no ROCm installed, nothing to check
+		if os.IsNotExist(err) {
+			return nil, err
+		}
+		return nil, err
+	}
+	curStr := strings.TrimSpace(string(data))
+	cur, err := semver.NewVersion(curStr)
+	if err != nil {
+		return nil, fmt.Errorf("invalid rocm version: %s", curStr)
+	}
+	return cur, nil
+}

cli/pkg/utils/pod.go

@@ -0,0 +1,111 @@
+package utils
+
+import (
+	"fmt"
+
+	corev1 "k8s.io/api/core/v1"
+)
+
+func AssertPodReady(pod *corev1.Pod) error {
+	if pod == nil {
+		return fmt.Errorf("pod is nil")
+	}
+
+	podKey := fmt.Sprintf("%s/%s", pod.Namespace, pod.Name)
+	if pod.DeletionTimestamp != nil {
+		return fmt.Errorf("pod %s is terminating", podKey)
+	}
+	if pod.Status.Phase != corev1.PodRunning {
+		return fmt.Errorf("pod %s is not running (phase=%s)", podKey, pod.Status.Phase)
+	}
+
+	if len(pod.Spec.InitContainers) > 0 {
+		initStatusByName := make(map[string]corev1.ContainerStatus, len(pod.Status.InitContainerStatuses))
+		for i := range pod.Status.InitContainerStatuses {
+			s := pod.Status.InitContainerStatuses[i]
+			initStatusByName[s.Name] = s
+		}
+		for _, ic := range pod.Spec.InitContainers {
+			s, ok := initStatusByName[ic.Name]
+			if !ok {
+				return fmt.Errorf("pod %s has not started init container %s yet", podKey, ic.Name)
+			}
+			if t := s.State.Terminated; t != nil {
+				if t.ExitCode != 0 {
+					return fmt.Errorf(
+						"init container %s in pod %s terminated (exitCode=%d, reason=%s, message=%s)",
+						s.Name, podKey, t.ExitCode, t.Reason, t.Message,
+					)
+				}
+				continue
+			}
+			if w := s.State.Waiting; w != nil {
+				return fmt.Errorf(
+					"init container %s in pod %s is waiting (reason=%s, message=%s)",
+					s.Name, podKey, w.Reason, w.Message,
+				)
+			}
+			return fmt.Errorf("pod %s init container %s is still running", podKey, s.Name)
+		}
+	}
+
+	readyCondFound := false
+	for i := range pod.Status.Conditions {
+		cond := pod.Status.Conditions[i]
+		if cond.Type != corev1.PodReady {
+			continue
+		}
+		readyCondFound = true
+		if cond.Status != corev1.ConditionTrue {
+			if cond.Reason != "" || cond.Message != "" {
+				return fmt.Errorf("pod %s is not ready (reason=%s, message=%s)", podKey, cond.Reason, cond.Message)
+			}
+			return fmt.Errorf("pod %s is not ready", podKey)
+		}
+		break
+	}
+	if !readyCondFound {
+		return fmt.Errorf("pod %s is not ready (missing Ready condition)", podKey)
+	}
+
+	statusByName := make(map[string]corev1.ContainerStatus, len(pod.Status.ContainerStatuses))
+	for i := range pod.Status.ContainerStatuses {
+		s := pod.Status.ContainerStatuses[i]
+		statusByName[s.Name] = s
+	}
+
+	for _, c := range pod.Spec.Containers {
+		cStatus, ok := statusByName[c.Name]
+		if !ok {
+			return fmt.Errorf("pod %s has not started container %s yet", podKey, c.Name)
+		}
+
+		if t := cStatus.State.Terminated; t != nil {
+			return fmt.Errorf(
+				"container %s in pod %s terminated (exitCode=%d, reason=%s, message=%s)",
+				cStatus.Name,
+				podKey,
+				t.ExitCode,
+				t.Reason,
+				t.Message,
+			)
+		}
+
+		if cStatus.State.Running == nil {
+			if w := cStatus.State.Waiting; w != nil {
+				return fmt.Errorf(
+					"container %s in pod %s is waiting (reason=%s, message=%s)",
+					cStatus.Name,
+					podKey,
+					w.Reason,
+					w.Message,
+				)
+			}
+			return fmt.Errorf("container %s in pod %s is not running", cStatus.Name, podKey)
+		}
+		if !cStatus.Ready {
+			return fmt.Errorf("container %s in pod %s is not ready", cStatus.Name, podKey)
+		}
+	}
+	return nil
+}

cli/pkg/utils/utils.go

@@ -321,3 +321,54 @@ func GetBufIOReaderOfTerminalInput() (*bufio.Reader, error) {
 	}
 	return bufio.NewReader(tty), nil
 }
+
+// ResolveSudoUserHomeAndIDs resolves the home directory, uid, and gid for the user
+// who invoked sudo. If not running under sudo, it falls back to the current user.
+// This is useful for commands that need to operate on the invoking user's home
+// directory rather than /root when running with sudo.
+func ResolveSudoUserHomeAndIDs(runtime connector.Runtime) (home, uid, gid string, err error) {
+	uid, err = runtime.GetRunner().Cmd("echo ${SUDO_UID:-}", false, false)
+	if err != nil {
+		return "", "", "", errors.Wrap(errors.WithStack(err), "get SUDO_UID failed")
+	}
+	gid, err = runtime.GetRunner().Cmd("echo ${SUDO_GID:-}", false, false)
+	if err != nil {
+		return "", "", "", errors.Wrap(errors.WithStack(err), "get SUDO_GID failed")
+	}
+	uid = strings.TrimSpace(uid)
+	gid = strings.TrimSpace(gid)
+
+	if uid == "" {
+		uid, err = runtime.GetRunner().Cmd("id -u", false, false)
+		if err != nil {
+			return "", "", "", errors.Wrap(errors.WithStack(err), "get current uid failed")
+		}
+		gid, err = runtime.GetRunner().Cmd("id -g", false, false)
+		if err != nil {
+			return "", "", "", errors.Wrap(errors.WithStack(err), "get current gid failed")
+		}
+		uid = strings.TrimSpace(uid)
+		gid = strings.TrimSpace(gid)
+	}
+
+	home, err = runtime.GetRunner().Cmd(fmt.Sprintf(`getent passwd %s | awk -F: 'NR==1{print $6; exit}'`, uid), false, false)
+	if err != nil {
+		home = ""
+	}
+	home = strings.TrimSpace(home)
+	if home == "" {
+		home, _ = runtime.GetRunner().Cmd(fmt.Sprintf(`awk -F: -v uid=%s '$3==uid {print $6; exit}' /etc/passwd 2>/dev/null`, uid), false, false)
+		home = strings.TrimSpace(home)
+	}
+	if home == "" {
+		home, err = runtime.GetRunner().Cmd("echo $HOME", false, false)
+		if err != nil {
+			return "", "", "", errors.Wrap(errors.WithStack(err), "get HOME failed")
+		}
+		home = strings.TrimSpace(home)
+	}
+	if home == "" {
+		return "", "", "", errors.New("resolve user home failed")
+	}
+	return home, uid, gid, nil
+}

cli/pkg/web5/jws/checkjws.go

@@ -19,7 +19,6 @@ import (
 )
 
 var (
-	DIDGateURL     = "https://did-gate-v3.bttcdn.com/1.0/name/"
 	DIDGateTimeout = 10 * time.Second
 	DIDCachePath   = "/var/lib/olares"
 )
@@ -90,7 +89,7 @@ type CheckJWSResult struct {
 }
 
 // resolveDID resolves a DID either from cache or from the DID gate
-func ResolveOlaresName(olares_id string) (*didcore.ResolutionResult, error) {
+func ResolveOlaresName(gateUrl, olares_id string) (*didcore.ResolutionResult, error) {
 	name := strings.Replace(olares_id, "@", ".", -1)
 	// Try to get from cache first
 	cached, err := getDB().Get([]byte(name), nil)
@@ -105,7 +104,7 @@ func ResolveOlaresName(olares_id string) (*didcore.ResolutionResult, error) {
 	client := &http.Client{
 		Timeout: DIDGateTimeout,
 	}
-	resp, err := client.Get(DIDGateURL + name)
+	resp, err := client.Get(gateUrl + name)
 	if err != nil {
 		return nil, fmt.Errorf("failed to fetch DID from gate: %w", err)
 	}
@@ -135,7 +134,7 @@ func ResolveOlaresName(olares_id string) (*didcore.ResolutionResult, error) {
 }
 
 // CheckJWS verifies a JWS and returns the terminus name, body and kid
-func CheckJWS(jws string, duration int64) (*CheckJWSResult, error) {
+func CheckJWS(gateUrl, jws string, duration int64) (*CheckJWSResult, error) {
 	var kid string
 	var name string
 	var timestamp int64
@@ -198,7 +197,7 @@ func CheckJWS(jws string, duration int64) (*CheckJWSResult, error) {
 	}
 
 	// Resolve DID
-	resolutionResult, err := ResolveOlaresName(name)
+	resolutionResult, err := ResolveOlaresName(gateUrl, name)
 	if err != nil {
 		return nil, fmt.Errorf("failed to resolve DID: %w", err)
 	}

daemon/go.mod

@@ -18,12 +18,12 @@ require (
 	bytetrade.io/web3os/bfl v0.0.0-00010101000000-000000000000
 	github.com/Masterminds/semver/v3 v3.4.0
 	github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2
-	github.com/beclab/Olares/cli v0.0.0-20251219153848-63d422037cf9
+	github.com/beclab/Olares/cli v0.0.0-20251230161135-5264df60cc33
 	github.com/beclab/Olares/framework/app-service v0.0.0-20251225061130-909b7656fd70
 	github.com/containerd/containerd v1.7.29
 	github.com/distribution/distribution/v3 v3.0.0
 	github.com/dustin/go-humanize v1.0.1
-	github.com/eball/zeroconf v0.2.2
+	github.com/eball/zeroconf v0.2.5
 	github.com/godbus/dbus/v5 v5.1.0
 	github.com/gofiber/fiber/v2 v2.52.9
 	github.com/google/gopacket v1.1.19

daemon/go.sum

@@ -24,8 +24,8 @@ github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPd
 github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
 github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so=
 github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw=
-github.com/beclab/Olares/cli v0.0.0-20251219153848-63d422037cf9 h1:YNHfPra2FqsKJ5mAxSWNVIK6VyWygRyZiNwfPqiFxlg=
-github.com/beclab/Olares/cli v0.0.0-20251219153848-63d422037cf9/go.mod h1:cYPcuju2yRSp9BQjIN/CC495dDOOvVoL42r/gvFlutk=
+github.com/beclab/Olares/cli v0.0.0-20251230161135-5264df60cc33 h1:WYuUPOT/p26aCDJGJEDai1v7YM6QHiaFDusBVynnbBY=
+github.com/beclab/Olares/cli v0.0.0-20251230161135-5264df60cc33/go.mod h1:ixhzBK5XIovsRB5djk44TChsOK4wum2q4y/hZxJKlNw=
 github.com/beclab/Olares/framework/app-service v0.0.0-20251225061130-909b7656fd70 h1:U3z6m0hokD1gzl788BrUdxCbDyAjdOBBXA8ilYgn6VQ=
 github.com/beclab/Olares/framework/app-service v0.0.0-20251225061130-909b7656fd70/go.mod h1:D9wl7y3obLqXMqfubMROMgdxWAwInnKNrFC//d0nyIA=
 github.com/beclab/bfl v0.3.36 h1:PgeSPGc+XoONiwFsKq9xX8rqcL4kVM1G/ut0lYYj/js=
@@ -87,8 +87,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/eball/echo/v4 v4.13.4-patch h1:5w83KQrEqrxhc1BO0BpRBHssC37vFrWualUM27Rt2sg=
 github.com/eball/echo/v4 v4.13.4-patch/go.mod h1:ORgy8LWTq8knpwgaz538rAJMri7WgpoAD6H3zYccn84=
-github.com/eball/zeroconf v0.2.2 h1:y23X67tLFlU+b35LyM9THXGsdC88IUz803G+mzfeSeE=
-github.com/eball/zeroconf v0.2.2/go.mod h1:eIbIjGYo9sSMaKWLcveHEPRWdyblz7q9ih2R1HnNw5M=
+github.com/eball/zeroconf v0.2.5 h1:RNINVvj8kbm/r4YoqYu/jWD57l5NJmvRUCfbjlIsbJg=
+github.com/eball/zeroconf v0.2.5/go.mod h1:eIbIjGYo9sSMaKWLcveHEPRWdyblz7q9ih2R1HnNw5M=
 github.com/ebitengine/purego v0.8.4 h1:CF7LEKg5FFOsASUj0+QwaXf8Ht6TlFxg09+S9wz0omw=
 github.com/ebitengine/purego v0.8.4/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/emicklei/go-restful/v3 v3.13.0 h1:C4Bl2xDndpU6nJ4bc1jXd+uTmYPVUwkD6bFY/oTyCes=

daemon/internel/apiserver/handlers/handler_did.go

@@ -2,8 +2,10 @@ package handlers
 
 import (
 	"net/http"
+	"net/url"
 
 	"github.com/beclab/Olares/cli/pkg/web5/jws"
+	"github.com/beclab/Olares/daemon/pkg/commands"
 	"github.com/gofiber/fiber/v2"
 	"k8s.io/klog/v2"
 )
@@ -14,8 +16,14 @@ func (h *Handlers) ResolveOlaresName(c *fiber.Ctx) error {
 		klog.Error("olaresName parameter is missing")
 		return h.ErrJSON(c, fiber.StatusBadRequest, "olaresName parameter is required")
 	}
+
 	klog.Infof("Received olaresName: %s", olaresName)
-	result, err := jws.ResolveOlaresName(olaresName)
+
+	didServiceURL, err := getDidGateURL()
+	if err != nil {
+		return h.ErrJSON(c, fiber.StatusInternalServerError, "Failed to get DID gate URL")
+	}
+	result, err := jws.ResolveOlaresName(didServiceURL, olaresName)
 	if err != nil {
 		klog.Errorf("Failed to resolve DID for %s: %v", olaresName, err)
 		return h.ErrJSON(c, fiber.StatusInternalServerError, "Failed to resolve DID")
@@ -46,7 +54,11 @@ func (h *Handlers) CheckJWS(c *fiber.Ctx) error {
 		body.Duration = int64(3 * 60 * 1000) // 3 minutes in milliseconds
 	}
 
-	result, err := jws.CheckJWS(body.JWS, body.Duration)
+	didServiceURL, err := getDidGateURL()
+	if err != nil {
+		return h.ErrJSON(c, fiber.StatusInternalServerError, "Failed to get DID gate URL")
+	}
+	result, err := jws.CheckJWS(didServiceURL, body.JWS, body.Duration)
 	if err != nil {
 		klog.Errorf("Failed to check JWS: %v", err)
 		return h.ErrJSON(c, fiber.StatusBadRequest, "Invalid JWS")
@@ -54,3 +66,12 @@ func (h *Handlers) CheckJWS(c *fiber.Ctx) error {
 
 	return h.OkJSON(c, "success", result)
 }
+
+func getDidGateURL() (string, error) {
+	didServiceURL, err := url.JoinPath(commands.OLARES_REMOTE_SERVICE, "/did/1.0/name/")
+	if err != nil {
+		klog.Errorf("failed to parse DID gate service URL: %v, Olares remote service: %s", err, commands.OLARES_REMOTE_SERVICE)
+		return "", err
+	}
+	return didServiceURL, nil
+}

daemon/internel/intranet/dns.go

@@ -81,7 +81,7 @@ func (s *mDNSServer) StartAll() error {
 			host:        &DNSConfig{Domain: domain},
 		}
 	}
-	klog.Info("Intranet mDNS server started")
+	klog.V(8).Info("Intranet mDNS server started")
 	return nil
 }
 

daemon/internel/intranet/proxy.go

@@ -84,8 +84,15 @@ func (p *proxyServer) Start() error {
 							clientIp = h
 						}
 					}
+
 					if c.IsWebSocket() {
 						ctx = context.WithValue(ctx, WSKey, true)
+						swp := c.Request().Header.Get("Sec-WebSocket-Protocol")
+						authToken := c.Request().Header.Get("X-Authorization")
+						if len(authToken) == 0 && len(swp) > 0 {
+							// handle missing auth token for websocket
+							c.Request().Header.Set("X-Authorization", swp)
+						}
 					}
 					r := c.Request().WithContext(ctx)
 					if clientIp != "" {
@@ -243,7 +250,7 @@ func (p *proxyServer) customDialContext(d *net.Dialer) func(ctx context.Context,
 		}
 
 		if isWs {
-			klog.Info("WebSocket connection detected, using upgraded dialer")
+			klog.Info("WebSocket connection detected, using upgraded dialer, ", addr)
 			return tlsDial(ctx, d, func(ctx context.Context, network, addr string) (net.Conn, error) {
 				return proxyDial(ctx, d, network, newAddr)
 			}, network, addr, &tls.Config{InsecureSkipVerify: true})

daemon/internel/intranet/server.go

@@ -147,6 +147,6 @@ func (s *Server) Reload(o *ServerOptions) error {
 		return fmt.Errorf("reload intranet server with %d errors", len(errs))
 	}
 
-	klog.Info("Intranet server reloaded")
+	klog.V(8).Info("Intranet server reloaded")
 	return nil
 }

daemon/internel/mdns/server.go

@@ -99,7 +99,7 @@ func (s *server) Restart() error {
 			instanceName = hostname
 		}
 
-		s.server, err = zeroconf.Register(instanceName, s.serviceName, "local.", hostname, s.port, []string{""}, []net.Interface{*iface})
+		s.server, err = zeroconf.RegisterAll(instanceName, s.serviceName, "local.", hostname, s.port, []string{""}, []net.Interface{*iface}, false, false, false)
 		if err != nil {
 			klog.Error("create mdns server error, ", err)
 			return err

daemon/internel/watcher/intranet/watchers.go

@@ -79,7 +79,7 @@ func (w *applicationWatcher) Watch(ctx context.Context) {
 				klog.Error("reload intranet server config error, ", err)
 				return
 			}
-			klog.Info("Intranet server config reloaded")
+			klog.V(8).Info("Intranet server config reloaded")
 		} else {
 			// Start the intranet server
 			err = w.intranetServer.Start(o)

daemon/internel/watcher/usb/watchers.go

@@ -20,6 +20,12 @@ func NewUsbWatcher() *usbWatcher {
 	return w
 }
 
+var UsbSerialKey = struct{}{}
+
+func WithSerial(ctx context.Context, serial string) context.Context {
+	return context.WithValue(ctx, UsbSerialKey, serial)
+}
+
 func (w *usbWatcher) Watch(ctx context.Context) {
 	retry := 1
 	devs, err := utils.DetectdUsbDevices(ctx)
@@ -55,6 +61,16 @@ func (w *usbWatcher) Watch(ctx context.Context) {
 		return
 	}
 
+	serial := ctx.Value(UsbSerialKey).(string)
+	if serial != "" {
+		klog.Info("mount usb device with serial, ", serial)
+		devs = utils.FilterArray(devs, utils.FilterBySerial(serial))
+		if len(devs) == 0 {
+			klog.Info("no usb device found with serial, ", serial)
+			return
+		}
+	}
+
 	mountedPath, err := utils.MountUsbDevice(ctx, commands.MOUNT_BASE_DIR, devs)
 	if err != nil {
 		klog.Error("mount usb error, ", err)
@@ -80,13 +96,13 @@ func (w *umountWatcher) Watch(ctx context.Context) {
 }
 
 func NewUsbMonitor(ctx context.Context) error {
-	return utils.MonitorUsbDevice(ctx, func(action string) error {
+	return utils.MonitorUsbDevice(ctx, func(action, serial string) error {
 		switch action {
 		case "add":
 			delay := time.NewTimer(2 * time.Second)
 			go func() {
 				<-delay.C
-				NewUsbWatcher().Watch(ctx)
+				NewUsbWatcher().Watch(WithSerial(ctx, serial))
 			}()
 		case "remove":
 			NewUmountWatcher().Watch(ctx)

daemon/pkg/utils/drivers_linux.go

@@ -119,7 +119,7 @@ func DetectdHddDevices(ctx context.Context) (usbDevs []storageDevice, err error)
 	return detectdStorageDevices(ctx, "ata")
 }
 
-func MonitorUsbDevice(ctx context.Context, cb func(action string) error) error {
+func MonitorUsbDevice(ctx context.Context, cb func(action, serial string) error) error {
 	filter := &usbmon.ActionFilter{Action: usbmon.ActionAll}
 	devs, err := usbmon.ListenFiltered(ctx, filter)
 	if err != nil {
@@ -137,8 +137,8 @@ func MonitorUsbDevice(ctx context.Context, cb func(action string) error) error {
 				fmt.Println("Path: " + dev.Path())
 				fmt.Println("Vendor: " + dev.Vendor())
 
-				if cb != nil {
-					err = cb(dev.Action())
+				if cb != nil && dev.Serial() != "" {
+					err = cb(dev.Action(), dev.Serial())
 					if err != nil {
 						klog.Error("usb action callback error, ", err, ", ", dev.Action())
 					}
@@ -197,6 +197,12 @@ func MountedHddPath(ctx context.Context) ([]string, error) {
 	return getMountedPath(hdds)
 }
 
+func FilterBySerial(serial string) func(dev storageDevice) bool {
+	return func(dev storageDevice) bool {
+		return strings.HasSuffix(serial, dev.IDSerial) || strings.HasSuffix(serial, dev.IDSerialShort)
+	}
+}
+
 func MountUsbDevice(ctx context.Context, mountBaseDir string, dev []storageDevice) (mountedPath []string, err error) {
 	mounter := mountutils.New("")
 	mountedList, err := mounter.List()

daemon/pkg/utils/drivers_macos.go

@@ -19,7 +19,7 @@ func DetectdHddDevices(ctx context.Context) (usbDevs []storageDevice, err error)
 	return
 }
 
-func MonitorUsbDevice(ctx context.Context, cb func(action string) error) error {
+func MonitorUsbDevice(ctx context.Context, cb func(action, id string) error) error {
 	klog.Warning("not implement")
 	return nil
 }
@@ -72,3 +72,9 @@ func MountedPath(ctx context.Context) ([]mountedPath, error) {
 	klog.Warning("not implement")
 	return nil, nil
 }
+
+func FilterBySerial(serial string) func(dev storageDevice) bool {
+	return func(dev storageDevice) bool {
+		return dev.IDSerial == serial || dev.IDSerialShort == serial
+	}
+}

daemon/pkg/utils/jws.go

@@ -18,15 +18,14 @@ func ValidateJWS(token string) (bool, string, error) {
 		klog.Errorf("failed to parse DID gate service URL: %v, Olares remote service: %s", err, commands.OLARES_REMOTE_SERVICE)
 		return false, "", err
 	}
-	jws.DIDGateURL = didServiceURL
 
 	// Validate the JWS token with a 20-minute expiration time
-	checkJWS, err := jws.CheckJWS(token, 20*60*1000)
+	checkJWS, err := jws.CheckJWS(didServiceURL, token, 20*60*1000)
 	if err != nil {
 		if strings.HasPrefix(err.Error(), "timestamp") {
 			err = fmt.Errorf("%v, server time: %s", err, time.Now().UTC().Format(time.RFC3339))
 		}
-		klog.Errorf("failed to check JWS: %v, on %s", err, jws.DIDGateURL)
+		klog.Errorf("failed to check JWS: %v, on %s", err, didServiceURL)
 		return false, "", err
 	}
 

daemon/pkg/utils/utils.go

@@ -0,0 +1,11 @@
+package utils
+
+func FilterArray[T any](items []T, fn func(T) bool) []T {
+	var filtered []T
+	for _, item := range items {
+		if fn(item) {
+			filtered = append(filtered, item)
+		}
+	}
+	return filtered
+}

docs/.vitepress/en.ts

@@ -6,19 +6,34 @@ const side = {
       text: "What is Olares",
       link: "/manual/overview",
       items: [
-        { text: "Compare Olares and NAS", link: "/manual/olares-vs-nas" },
-        { text: "Help and support", link: "/manual/help/request-technical-support"}
-          //  collapsed: true,
-          //   items: [
-            // { text: "FAQs", link: "/manual/help/faqs" },
-            //    {
-            //     text: "Request support",
-          //     link: "/manual/help/request-technical-support",
-          //  },
-            //{
-            //  text: "Troubleshooting Guide",
-            //  link: "/manual/help/troubleshooting-guide",
-            // },
+        // { text: "Compare Olares and NAS", link: "/manual/olares-vs-nas" },
+        {
+          text: "FAQs",
+          //           link: "/manual/help/faqs",
+          collapsed: true,
+          items: [
+            {
+              text: "Olares FAQs",
+              link: "/manual/help/olares",
+            },
+            {
+              text: "Installation FAQs",
+              link: "/manual/help/installation",
+            },
+            {
+              text: "Usage FAQs",
+              link: "/manual/help/usage",
+            },
+            //             {
+            //               text: "Request support",
+            //               link: "/manual/help/request-technical-support",
+            //             },
+            //             {
+            //              text: "Troubleshooting",
+            //              link: "/manual/help/troubleshooting",
+            //             },
+          ],
+        },
       ],
     },
     {
@@ -109,7 +124,7 @@ const side = {
           link: "/manual/larepass/back-up-mnemonics"
         },
         {
-          text: "Access Olares locally",
+          text: "Access Olares securely",
           link: "/manual/get-started/local-access",
         },
         {
@@ -127,39 +142,39 @@ const side = {
           text: "Manage accounts",
           collapsed: true,
           items: [
-            {text: "Create accounts", link:"/manual/larepass/create-account"},
-            {text: "Back up mnemonics", link: "/manual/larepass/back-up-mnemonics"},
-            {text: "Manage integrations", link:"/manual/larepass/integrations"},
+            { text: "Create accounts", link: "/manual/larepass/create-account" },
+            { text: "Back up mnemonics", link: "/manual/larepass/back-up-mnemonics" },
+            { text: "Manage integrations", link: "/manual/larepass/integrations" },
           ],
         },
-        {text: "Use VPN", link:"/manual/larepass/private-network"},
+        { text: "Use VPN", link: "/manual/larepass/private-network" },
         {
           text: "Manage device",
           collapsed: true,
           items: [
-            {text: "Activate Olares", link:"/manual/larepass/activate-olares"},
-            {text: "Manage Olares", link:"/manual/larepass/manage-olares"},
+            { text: "Activate Olares", link: "/manual/larepass/activate-olares" },
+            { text: "Manage Olares", link: "/manual/larepass/manage-olares" },
           ],
         },
-        {text: "Manage files", link:"/manual/larepass/manage-files"},
-         // collapsed: true,
-          //items: [
-          //  {text: "Common file operations", link:"/manual/larepass/manage-files"},
-           // {text: "Sync and share", link:"/manual/larepass/sync-share"}
-         // ]
-       // },
+        { text: "Manage files", link: "/manual/larepass/manage-files" },
+        // collapsed: true,
+        //items: [
+        //  {text: "Common file operations", link:"/manual/larepass/manage-files"},
+        // {text: "Sync and share", link:"/manual/larepass/sync-share"}
+        // ]
+        // },
         {
           text: "Manage passwords",
           collapsed: true,
           items: [
-            {text: "Autofill passwords", link: "/manual/larepass/autofill"},
-            {text: "Generate 2FA codes", link: "/manual/larepass/two-factor-verification"},
+            { text: "Autofill passwords", link: "/manual/larepass/autofill" },
+            { text: "Generate 2FA codes", link: "/manual/larepass/two-factor-verification" },
           ],
         },
-        {
+        /*{
           text: "Manage knowledge",
           link: "/manual/larepass/manage-knowledge",
-        },
+        },*/
       ],
     },
     {
@@ -168,7 +183,24 @@ const side = {
       link: "/manual/olares/",
       items: [
         { text: "Desktop", link: "/manual/olares/desktop", },
-        { text: "Market", link: "/manual/olares/market", },
+        {
+          text: "Market",
+          collapsed: true,
+          items: [
+            {
+              text: "Basic operations",
+              link: "/manual/olares/market/market",
+            },
+            {
+              text: "Clone applications",
+              link: "/manual/olares/market/clone-apps",
+            },
+            {
+              text: "Manage paid applications",
+              link: "/manual/olares/market/purchase-paid-apps",
+            },
+          ],
+        },
         {
           text: "Files",
           collapsed: true,
@@ -178,18 +210,26 @@ const side = {
               text: "Basic file operations",
               link: "/manual/olares/files/add-edit-download",
             },
-         //   {
-        //      text: "Sync and share",
-         //     link: "/manual/larepass/sync-share",
-         //   },
+            //   {
+            //      text: "Sync and share",
+            //     link: "/manual/larepass/sync-share",
+            //   },
+            {
+              text: "Share files",
+              link: "/manual/olares/files/share-files",
+            },
+            {
+              text: "Sync files to local",
+              link: "/manual/olares/files/sync-files",
+            },
             {
               text: "Mount SMB",
               link: "/manual/olares/files/mount-SMB",
             },
-           {
-             text: "Mount cloud storage",
-             link: "/manual/olares/files/mount-cloud-storage",
-           },
+            {
+              text: "Mount cloud storage",
+              link: "/manual/olares/files/mount-cloud-storage",
+            },
           ],
         },
         {
@@ -224,17 +264,32 @@ const side = {
               text: "Basic operations",
               link: "/manual/olares/wise/basics",
             },
-            {
+            /*{
               text: "Get recommendation engine",
               link: "/manual/olares/wise/recommend",
-            },
+            },*/
             {
               text: "Manage your feeds",
               link: "/manual/olares/wise/subscribe",
             },
             {
-              text: "Organize your knowledge",
+              text: "Manage cookies",
+              link: "/manual/olares/wise/manage-cookies",
+            },
+            {
+              text: "Organize with filters",
               link: "/manual/olares/wise/filter",
+              collapsed: true,
+              items: [
+                {
+                  text: "Filter syntax",
+                  link: "/manual/olares/wise/filter-syntax-guide",
+                },
+                {
+                  text: "Filter example",
+                  link: "/manual/olares/wise/filter-examples",
+                },
+              ],
             },
           ],
         },
@@ -305,16 +360,16 @@ const side = {
                   link: "/manual/olares/settings/manage-app-env",
                 },
               ],
-              },
+            },
             {
               text: "Manage integrations",
-              link:"/manual/olares/settings/integrations",
-             },
-             {
+              link: "/manual/olares/settings/integrations",
+            },
+            {
               text: "Customize appearance",
-              link:"/manual/olares/settings/language-appearance",
-             },
-            {text: "Manage VPN", link: "/manual/olares/settings/remote-access",},
+              link: "/manual/olares/settings/language-appearance",
+            },
+            { text: "Manage VPN", link: "/manual/olares/settings/remote-access", },
             {
               text: "Configure network",
               collapsed: true,
@@ -325,54 +380,59 @@ const side = {
                 },
                 {
                   text: "Set up hosts file",
-                  link:"/manual/olares/settings/set-up-hosts",
+                  link: "/manual/olares/settings/set-up-hosts",
                 },
               ],
-             },
-            {text: "Manage GPU", link: "/manual/olares/settings/gpu-resource"},
-            {text: "Set video playback", link: "/manual/olares/settings/video"},
+            },
+            { text: "Manage GPU", link: "/manual/olares/settings/gpu-resource" },
+            { text: "Set video playback", link: "/manual/olares/settings/video" },
+            { text: "Manage search rules", link: "/manual/olares/settings/search" },
             {
               text: "Backup and restore",
               collapsed: true,
               items: [
-                {text: "Backup", link: "/manual/olares/settings/backup"},
-                {text: "Restore", link: "/manual/olares/settings/restore"},
+                { text: "Backup", link: "/manual/olares/settings/backup" },
+                { text: "Restore", link: "/manual/olares/settings/restore" },
               ],
             },
-            {text: "Developer resources", link: "/manual/olares/settings/developer"},
-            ]
-          },
-          {text: "Dashboard", link: "/manual/olares/resources-usage"},
-          {text: "Profile", link: "/manual/olares/profile"},
-        ],
+            { text: "Developer resources", link: "/manual/olares/settings/developer" },
+          ]
+        },
+        { text: "Dashboard", link: "/manual/olares/resources-usage" },
+        { text: "Profile", link: "/manual/olares/profile" },
+      ],
     },
-      {
-        text: "Best practices",
-        link: "/manual/best-practices/",
-        collapsed: true,
-        items: [
-          {
-            text: "Set up custom domain",
-            link: "/manual/best-practices/set-custom-domain",
-          },
-          {
-            text: "Manage knowledge with Wise",
-            link: "/manual/best-practices/organize-content",
-          },
-          {
-            text: "Install a multi-node Olares cluster",
-            link: "/manual/best-practices/install-olares-multi-node",
-          },
-          {
-            text: "Install Olares on PVE with GPU Passthrough",
-            link: "/manual/best-practices/install-olares-gpu-passthrough",
-          },
-          {
-            text: "Expand storage in Olares",
+    {
+      text: "Tutorials",
+      link: "/manual/best-practices/",
+      collapsed: true,
+      items: [
+        {
+          text: "Set up custom domain",
+          link: "/manual/best-practices/set-custom-domain",
+        },
+        {
+          text: "Manage knowledge with Wise",
+          link: "/manual/best-practices/organize-content",
+        },
+        {
+          text: "Install a multi-node Olares cluster",
+          link: "/manual/best-practices/install-olares-multi-node",
+        },
+        {
+          text: "Install Olares on PVE with GPU Passthrough",
+          link: "/manual/best-practices/install-olares-gpu-passthrough",
+        },
+        {
+          text: "Expand storage in Olares",
           link: "/manual/best-practices/expand-storage-in-olares",
         },
-        ],
-      },
+        {
+          text: "Access Olares locally",
+          link: "/manual/best-practices/local-access",
+        },
+      ],
+    },
     { text: "Glossary", link: "/manual/glossary" },
   ],
   "/space/": [
@@ -421,83 +481,106 @@ const side = {
     },
   ],
   "/use-cases/": [
-  {
-    text: "Use cases",
-    link: "/use-cases/",
-    items: [
-      {
-        text: "Stable Diffusion",
-        link: "/use-cases/stable-diffusion",
-      },
-      {
-        text: "ComfyUI",
-        link: "/use-cases/comfyui",
-        collapsed: true,
-        items: [
-          {
-            text: "Manage ComfyUI",
-            link: "/use-cases/comfyui-launcher",
-          },
-          {
-            text: "Use ComfyUI for Krita",
-            link: "/use-cases/comfyui-for-krita",
-          },
-        ]
-      },
-      {
-        text: "Ollama",
-        link: "/use-cases/ollama",
-      },
-      {
-        text: "Open WebUI",
-        link: "/use-cases/openwebui",
-      },
-      {
-        text: "Perplexica",
-        link: "/use-cases/perplexica",
-      },
-      {
-        text: "Dify",
-        link: "/use-cases/dify",
-      },
-      {
-        text: "Jellyfin",
-        link: "/use-cases/stream-media",
-      },
-      {
-        text: "Steam",
-        link: "/use-cases/stream-game",
-      },
-      {
-        text: "Redroid",
-        link: "/use-cases/host-cloud-android",
-      },
-      {
-        text: "Windows",
-        link: "/use-cases/windows",
-      }, 
-      {
-        text: "DeerFlow",
-        link: "/use-cases/deerflow",
-      }, 
-      {
-        text: "Duix.Avatar",
-        link: "/use-cases/duix-avatar",
-      },
-      {
-        text: "ACE-Step",
-        link: "/use-cases/ace-step",
-      },      
-    ],
-  },
- ],
+    {
+      text: "Use cases",
+      link: "/use-cases/",
+      items: [
+        {
+          text: "Stable Diffusion",
+          link: "/use-cases/stable-diffusion",
+        },
+        {
+          text: "ComfyUI",
+          link: "/use-cases/comfyui",
+          collapsed: true,
+          items: [
+            {
+              text: "Manage ComfyUI",
+              link: "/use-cases/comfyui-launcher",
+            },
+            {
+              text: "Use ComfyUI for Krita",
+              link: "/use-cases/comfyui-for-krita",
+            },
+          ]
+        },
+        {
+          text: "Ollama",
+          link: "/use-cases/ollama",
+        },
+        {
+          text: "Open WebUI",
+          link: "/use-cases/openwebui",
+        },
+        {
+          text: "Perplexica",
+          link: "/use-cases/perplexica",
+        },
+        {
+          text: "Dify",
+          link: "/use-cases/dify",
+        },
+        {
+          text: "Jellyfin",
+          link: "/use-cases/stream-media",
+        },
+        {
+          text: "Steam",
+          collapsed: true,
+          items: [
+            {
+              text: "Play directly on Olares",
+              link: "/use-cases/play-games-directly",
+            },
+            {
+              text: "Stream to other devices",
+              link: "/use-cases/stream-game",
+            }
+          ]
+        },
+        //         {
+        //           text: "Redroid",
+        //           link: "/use-cases/host-cloud-android",
+        //         },
+        {
+          text: "Windows",
+          link: "/use-cases/windows",
+        },
+        {
+          text: "DeerFlow",
+          link: "/use-cases/deerflow",
+        },
+        {
+          text: "Duix.Avatar",
+          link: "/use-cases/duix-avatar",
+        },
+        {
+          text: "ACE-Step",
+          link: "/use-cases/ace-step",
+        },
+        {
+          text: "Stirling PDF",
+          link: "/use-cases/stirling-pdf",
+        },
+        {
+          text: "PDFMathTranslate",
+          link: "/use-cases/pdfmathtranslate",
+        },
+        {
+          text: "LobeChat",
+          link: "/use-cases/lobechat",
+        },
+      ],
+    },
+  ],
   "/developer/": [
     {
       text: "Concepts",
       link: "/developer/concepts/",
       items: [
         { text: "Olares architecture", link: "/developer/concepts/system-architecture" },
-        { text: "Olares ID",
+        {
+          text: "Olares ID",
           link: "/developer/concepts/olares-id",
           collapsed: true,
           items: [
@@ -534,7 +617,7 @@ const side = {
         { text: "Secrets", link: "/developer/concepts/secrets" },
       ],
     },
-      {
+    {
       text: "Installation deep-dive",
       link: "/developer/install/",
       items: [
@@ -559,74 +642,55 @@ const side = {
           link: "/developer/install/cli/olares-cli",
           collapsed: true,
           items: [
-            { text: "gpu", link: "/developer/install/cli/gpu" },
-            { text: "osinfo", link: "/developer/install/cli/osinfo" },
-            { text: "node", link: "/developer/install/cli/node" },
             {
               text: "backups",
               link: "/developer/install/cli/backups",
               collapsed: true,
               items: [
-                  {text: "download", link: "/developer/install/cli/backups-download"},
-                  {text: "region", link: "/developer/install/cli/backups-region"},
-                  {text: "backup", link: "/developer/install/cli/backups-backup"},
-                  {text: "restore", link: "/developer/install/cli/backups-restore"},
-                  {text: "snapshots", link: "/developer/install/cli/backups-snapshots"},
-                  ],
-            },
+                { text: "backup", link: "/developer/install/cli/backups-backup" },
+                { text: "download", link: "/developer/install/cli/backups-download" },
+                { text: "region", link: "/developer/install/cli/backups-region" },
+                { text: "restore", link: "/developer/install/cli/backups-restore" },
+                { text: "snapshots", link: "/developer/install/cli/backups-snapshots" },
+              ],
+            }, 
+            { text: "change-ip", link: "/developer/install/cli/change-ip" },
+            { text: "disk", link: "/developer/install/cli/disk" },   
+            { text: "download", link: "/developer/install/cli/download" },
+            { text: "gpu", link: "/developer/install/cli/gpu" },
+            { text: "info", link: "/developer/install/cli/info" },         
+            { text: "install", link: "/developer/install/cli/install" },
+            { text: "logs", link: "/developer/install/cli/logs" },
+            { text: "node", link: "/developer/install/cli/node" },
+            { text: "osinfo", link: "/developer/install/cli/osinfo" },
+            { text: "precheck", link: "/developer/install/cli/precheck" },
+            { text: "prepare", link: "/developer/install/cli/prepare" },
+            { text: "release", link: "/developer/install/cli/release" },
+            { text: "start", link: "/developer/install/cli/start" },
+            { text: "stop", link: "/developer/install/cli/stop" },
+            { text: "uninstall", link: "/developer/install/cli/uninstall" },
+            { text: "upgrade", link: "/developer/install/cli/upgrade" },
             {
-              text: "change-ip",
-              link: "/developer/install/cli/change-ip",
-            },
-            {
-              text: "download",
-              link: "/developer/install/cli/download",
-            },
-            { text: "info", link: "/developer/install/cli/info" },
-            {
-              text: "install",
-              link: "/developer/install/cli/install",
-            },
-            {
-              text: "user activate",
-              link: "/developer/install/cli/user-activate",
-            },
-            {
-              text: "logs",
-              link: "/developer/install/cli/logs",
-            },
-            {
-              text: "precheck",
-              link: "/developer/install/cli/precheck",
-            },
-            {
-              text: "prepare",
-              link: "/developer/install/cli/prepare",
-            },
-            {
-              text: "release",
-              link: "/developer/install/cli/release",
-            },
-            {
-              text: "start",
-              link: "/developer/install/cli/start",
-            },
-            {
-              text: "stop",
-              link: "/developer/install/cli/stop",
-            },
-            {
-              text: "uninstall",
-              link: "/developer/install/cli/uninstall",
+              text: "user",
+              link: "/developer/install/cli/user",
+              collapsed: true,
+              items: [
+                { text: "activate", link: "/developer/install/cli/user-activate" },
+                { text: "create", link: "/developer/install/cli/user-create" },
+                { text: "delete", link: "/developer/install/cli/user-delete" },
+                { text: "get", link: "/developer/install/cli/user-get" },
+                { text: "list", link: "/developer/install/cli/user-list" },
+                { text: "reset-password", link: "/developer/install/cli/user-reset-password" },
+              ],
             },
           ],
         },
-            {
-            text: "Olares versioning",
-            link: "/developer/install/versioning",
-          },
-    ],
-  },
+        {
+          text: "Olares versioning",
+          link: "/developer/install/versioning",
+        },
+      ],
+    },
     {
       text: "Develop Olares apps",
       link: "/developer/develop/",
@@ -682,43 +746,43 @@ const side = {
         //  items: [
         //    {
         //       text: "terminus-info",
-      //      link: "/developer/develop/advanced/terminus-info",
+        //      link: "/developer/develop/advanced/terminus-info",
         //     },
         //     {
         //       text: "Service provider",
-      //      link: "/developer/develop/advanced/provider",
+        //      link: "/developer/develop/advanced/provider",
         //      },
         //     {
         //        text: "AI",
-      //        link: "/developer/develop/advanced/ai",
+        //        link: "/developer/develop/advanced/ai",
         //       },
         //      { text: "Cookie", link: "/developer/develop/advanced/cookie" },
         //     { text: "Database", link: "/developer/develop/advanced/database" },
         //     {
         //       text: "Account",
-      //       link: "/developer/develop/advanced/account",
+        //       link: "/developer/develop/advanced/account",
         //      },
         //     {
         //       text: "Market",
-      //       link: "/developer/develop/advanced/market",
+        //       link: "/developer/develop/advanced/market",
         //      },
         //       {
         //       text: "Websocket",
-      //       link: "/developer/develop/advanced/websocket",
+        //       link: "/developer/develop/advanced/websocket",
         //     },
         //      {
         //       text: "File upload",
-      //       link: "/developer/develop/advanced/file-upload",
+        //       link: "/developer/develop/advanced/file-upload",
         //      },
         //     {
         //       text: "Secret",
-      //       link: "/developer/develop/advanced/secret",
+        //       link: "/developer/develop/advanced/secret",
         //      },
         //      {
         //        text: "Kubesphere",
-      //      link: "/developer/develop/advanced/kubesphere",
+        //      link: "/developer/develop/advanced/kubesphere",
         //      },
-      //   ],
+        //   ],
         //   },
         {
           text: "Submit application",
@@ -756,86 +820,86 @@ const side = {
             },
           ],
         },
-      {
-        text: "Develop protocols",
-        collapsed: true,
-        items: [
-          {
-            text: "Contract",
-            link: "/developer/contribute/olares-id/contract/contract",
-            collapsed: true,
-            items: [
-              {
-                text: "Architecture",
-                link: "/developer/contribute/olares-id/contract/architecture",
-              },
-              {
-                text: "DID",
-                collapsed: true,
-                items: [
-                  {
-                    text: "Design",
-                    link: "/developer/contribute/olares-id/contract/did/design",
-                  },
-                  {
-                    text: "Official Taggers",
-                    link: "/developer/contribute/olares-id/contract/did/official-taggers",
-                  },
-                  {
-                    text: "Release History",
-                    link: "/developer/contribute/olares-id/contract/did/release-history",
-                  },
-                  {
-                    text: "FAQ",
-                    link: "/developer/contribute/olares-id/contract/did/faq",
-                  },
-                ],
-              },
-              {
-                text: "Reputation",
-                link: "/developer/contribute/olares-id/contract/contract-reputation",
-              },
-              {
-                text: "Manage",
-                collapsed: true,
-                items: [
-                  {
-                    text: "Contract",
-                    link: "/developer/contribute/olares-id/contract/manage/contract",
-                  },
-                  {
-                    text: "SDK",
-                    link: "/developer/contribute/olares-id/contract/manage/sdk",
-                  },
-                  {
-                    text: "Environment",
-                    link: "/developer/contribute/olares-id/contract/manage/environment",
-                  },
-                ],
-              },
-            ],
-          },
-          {
-            text: "Verifiable Credential",
-            link: "/developer/contribute/olares-id/verifiable-credential/overview",
-            collapsed: true,
-            items: [
-              {
-                text: "Issuer",
-                link: "/developer/contribute/olares-id/verifiable-credential/issuer",
-              },
-              {
-                text: "Verifer",
-                link: "/developer/contribute/olares-id/verifiable-credential/verifer",
-              },
-              {
-                text: "Olares",
-                link: "/developer/contribute/olares-id/verifiable-credential/olares",
-              },
-            ],
-          },
-        ],
-       },
+        {
+          text: "Develop protocols",
+          collapsed: true,
+          items: [
+            {
+              text: "Contract",
+              link: "/developer/contribute/olares-id/contract/contract",
+              collapsed: true,
+              items: [
+                {
+                  text: "Architecture",
+                  link: "/developer/contribute/olares-id/contract/architecture",
+                },
+                {
+                  text: "DID",
+                  collapsed: true,
+                  items: [
+                    {
+                      text: "Design",
+                      link: "/developer/contribute/olares-id/contract/did/design",
+                    },
+                    {
+                      text: "Official Taggers",
+                      link: "/developer/contribute/olares-id/contract/did/official-taggers",
+                    },
+                    {
+                      text: "Release History",
+                      link: "/developer/contribute/olares-id/contract/did/release-history",
+                    },
+                    {
+                      text: "FAQ",
+                      link: "/developer/contribute/olares-id/contract/did/faq",
+                    },
+                  ],
+                },
+                {
+                  text: "Reputation",
+                  link: "/developer/contribute/olares-id/contract/contract-reputation",
+                },
+                {
+                  text: "Manage",
+                  collapsed: true,
+                  items: [
+                    {
+                      text: "Contract",
+                      link: "/developer/contribute/olares-id/contract/manage/contract",
+                    },
+                    {
+                      text: "SDK",
+                      link: "/developer/contribute/olares-id/contract/manage/sdk",
+                    },
+                    {
+                      text: "Environment",
+                      link: "/developer/contribute/olares-id/contract/manage/environment",
+                    },
+                  ],
+                },
+              ],
+            },
+            {
+              text: "Verifiable Credential",
+              link: "/developer/contribute/olares-id/verifiable-credential/overview",
+              collapsed: true,
+              items: [
+                {
+                  text: "Issuer",
+                  link: "/developer/contribute/olares-id/verifiable-credential/issuer",
+                },
+                {
+                  text: "Verifer",
+                  link: "/developer/contribute/olares-id/verifiable-credential/verifer",
+                },
+                {
+                  text: "Olares",
+                  link: "/developer/contribute/olares-id/verifiable-credential/olares",
+                },
+              ],
+            },
+          ],
+        },
       ],
     },
   ],
@@ -856,4 +920,4 @@ export const en = defineConfig({
 
     sidebar: side,
   },
-});
+});

docs/.vitepress/theme/components/AppLinkCN.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+const targetUrl = 'https://www.olares.cn/larepass'
+</script>
+
+<template>
+  <a :href="targetUrl" target="_blank" rel="noreferrer" class="app-link">
+    <slot>LarePass 下载页面</slot>
+  </a>
+</template>

docs/.vitepress/theme/components/AppLinkGlobal.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+const targetUrl = 'https://www.olares.com/larepass'
+</script>
+
+<template>
+  <a :href="targetUrl" target="_blank" rel="noreferrer" class="app-link">
+    <slot>LarePass Download page</slot>
+  </a>
+</template>

docs/.vitepress/theme/index.ts

@@ -14,6 +14,9 @@ import OSTabs from "./components/OStabs.vue";
 import VersionSwitcher from "./components/VersionSwitcher.vue";
 import _ from "lodash";
 import { redirects } from './redirects';
+import AppLinkGlobal from './components/AppLinkGlobal.vue'
+import AppLinkCN from './components/AppLinkCN.vue'
+
 
 const LANGUAGE_LOCAL_KEY = "language";
 let isMenuChange = false;
@@ -27,6 +30,8 @@ enhanceApp({ app, router }: { app: App; router: Router }) {
     app.component("FilterableList", FilterableList);
     app.component("OSTabs", OSTabs);
     app.component("VersionSwitcher", VersionSwitcher);
+    app.component('AppLinkGlobal', AppLinkGlobal)
+    app.component('AppLinkCN', AppLinkCN)
 
       router.onBeforeRouteChange = (to: string) => {
           const path = to.replace(/\.html$/i, ''),
@@ -142,4 +147,4 @@ enhanceApp({ app, router }: { app: App; router: Router }) {
       }
     );
   },
-};
+};

docs/.vitepress/zh.ts

@@ -6,23 +6,36 @@ const side = {
       text: "Olares 是什么？",
       link: "/zh/manual/overview",
       items: [
-        // { text: "应用场景", link: "/zh/manual/why-olares" },
-        //{ text: "功能对比", link: "/zh/manual/feature-overview" },
-        { text: "比较 Olares 和 NAS", link: "/zh/manual/olares-vs-nas" },
-        {text: "帮助与支持", link: "/zh/manual/help/request-technical-support",}
-        //      collapsed: true,
-        //      items: [
-        //     { text: "常见问题", link: "/zh/manual/help/faqs" },
-        //     {
-        //       text: "技术支持",
-      //      link: "/zh/manual/help/request-technical-support",
-        //       },
+        // { text: "比较 Olares 和 NAS", link: "/zh/manual/olares-vs-nas" },
+        {
+          text: "常见问题",
+          //              link: "/zh/manual/help/faqs",
+          collapsed: true,
+          items: [
+            {
+              text: "产品",
+              link: "/zh/manual/help/olares",
+            },
+            {
+              text: "安装激活",
+              link: "/zh/manual/help/installation",
+            },
+            {
+              text: "使用",
+              link: "/zh/manual/help/usage",
+            },
+            //     {
+            //       text: "技术支持",
+            //      link: "/zh/manual/help/request-technical-support",
+            //       },
             //     {
             //       text: "Troubleshooting Guide",
             //       link: "/zh/manual/help/troubleshooting-guide",
             //     },
           ],
         },
+      ],
+    },
     {
       text: "快速开始",
       collapsed: false,
@@ -110,7 +123,7 @@ const side = {
           link: "/zh/manual/larepass/back-up-mnemonics",
         },
         {
-          text: "内网访问 Olares",
+          text: "安全访问 Olares",
           link: "zh/manual/get-started/local-access",
         },
         {
@@ -128,39 +141,39 @@ const side = {
           text: "管理账户",
           collapsed: true,
           items: [
-            {text: "创建账户", link:"/zh/manual/larepass/create-account"},
-            {text: "备份助记词", link: "/zh/manual/larepass/back-up-mnemonics"},
-            {text: "管理集成", link:"/zh/manual/larepass/integrations"},
+            { text: "创建账户", link: "/zh/manual/larepass/create-account" },
+            { text: "备份助记词", link: "/zh/manual/larepass/back-up-mnemonics" },
+            { text: "管理集成", link: "/zh/manual/larepass/integrations" },
           ],
         },
-        {text: "使用专用网络", link:"/zh/manual/larepass/private-network"},
+        { text: "使用专用网络", link: "/zh/manual/larepass/private-network" },
         {
           text: "管理设备",
           collapsed: true,
           items: [
-            {text: "激活 Olares", link:"/zh/manual/larepass/activate-olares"},
-            {text: "管理 Olares", link:"/zh/manual/larepass/manage-olares"},
+            { text: "激活 Olares", link: "/zh/manual/larepass/activate-olares" },
+            { text: "管理 Olares", link: "/zh/manual/larepass/manage-olares" },
           ],
         },
-        {text: "管理文件", link:"/zh/manual/larepass/manage-files"},
-      //    collapsed: true,
+        { text: "管理文件", link: "/zh/manual/larepass/manage-files" },
+        //    collapsed: true,
         //    items: [
         //    {text: "常用文件操作", link:"/zh/manual/larepass/manage-files"},
         //    {text: "同步与共享", link:"/zh/manual/larepass/sync-share"}
-      //  ]
+        //  ]
         // },
         {
           text: "管理密码",
           collapsed: true,
           items: [
-            {text: "自动填充", link: "/zh/manual/larepass/autofill"},
-            {text: "双重验证", link: "/zh/manual/larepass/two-factor-verification"},
+            { text: "自动填充", link: "/zh/manual/larepass/autofill" },
+            { text: "双重验证", link: "/zh/manual/larepass/two-factor-verification" },
           ],
         },
-        {
+        /*{
           text: "管理内容",
           link: "/zh/manual/larepass/manage-knowledge",
-        },
+        },*/
       ],
     },
     {
@@ -169,7 +182,24 @@ const side = {
       "link": "/zh/manual/olares/",
       "items": [
         { "text": "桌面", "link": "/zh/manual/olares/desktop" },
-        { "text": "应用市场", "link": "/zh/manual/olares/market" },
+        {
+          "text": "应用市场",
+          "collapsed": true,
+          "items": [
+            {
+              "text": "基本操作",
+              "link": "/zh/manual/olares/market/market"
+            },
+            {
+              "text": "管理付费应用",
+              "link": "/zh/manual/olares/market/purchase-paid-apps"
+            },
+            {
+              "text": "克隆应用",
+              "link": "/zh/manual/olares/market/clone-apps"
+            },
+          ],
+        },
         {
           "text": "文件管理器",
           "collapsed": true,
@@ -181,8 +211,16 @@ const side = {
             },
             //{
             //   "text": "同步与共享",
-          //  "link": "/zh/manual/larepass/sync-share"
+            //  "link": "/zh/manual/larepass/sync-share"
             //  },
+            {
+              "text": "分享文件",
+              "link": "/zh/manual/olares/files/share-files"
+            },
+            {
+              "text": "同步文件至本地",
+              "link": "/zh/manual/olares/files/sync-files"
+            },
             {
               "text": "挂载 SMB",
               "link": "/zh/manual/olares/files/mount-SMB"
@@ -225,19 +263,34 @@ const side = {
               "text": "基本操作",
               "link": "/zh/manual/olares/wise/basics"
             },
-            {
+            /*{
               "text": "获取推荐引擎",
               "link": "/zh/manual/olares/wise/recommend"
-            },
+            },*/
             {
               "text": "管理订阅",
               "link": "/zh/manual/olares/wise/subscribe"
             },
             {
-              "text": "整理知识",
-              "link": "/zh/manual/olares/wise/filter"
-            }
-          ]
+              text: "管理 Cookie",
+              link: "/zh/manual/olares/wise/manage-cookies",
+            },
+            {
+              "text": "管理知识",
+              "link": "/zh/manual/olares/wise/filter",
+              collapsed: true,
+              items: [
+                {
+                  "text": "过滤语法参考",
+                  "link": "/zh/manual/olares/wise/filter-syntax-guide"
+                },
+                {
+                  "text": "过滤视图示例",
+                  "link": "/zh/manual/olares/wise/filter-examples"
+                }
+              ],
+            },
+          ],
         },
         {
           "text": "控制面板",
@@ -271,7 +324,7 @@ const side = {
           "collapsed": true,
           "link": "/zh/manual/olares/settings/",
           "items": [
-            {"text": "我的 Olares", link: "/zh/manual/olares/settings/my-olares"},
+            { "text": "我的 Olares", link: "/zh/manual/olares/settings/my-olares" },
             {
               "text": "管理用户",
               "collapsed": true,
@@ -303,16 +356,16 @@ const side = {
                   link: "/zh/manual/olares/settings/manage-app-env",
                 },
               ],
-              },
+            },
             {
               "text": "管理集成",
-              "link":"/zh/manual/olares/settings/integrations",
-             },
-             {
+              "link": "/zh/manual/olares/settings/integrations",
+            },
+            {
               "text": "自定义外观",
-              "link":"/zh/manual/olares/settings/language-appearance",
-             },
-            {text: "管理 VPN", link: "/zh/manual/olares/settings/remote-access",},
+              "link": "/zh/manual/olares/settings/language-appearance",
+            },
+            { text: "管理 VPN", link: "/zh/manual/olares/settings/remote-access", },
             {
               "text": "配置网络",
               "collapsed": true,
@@ -323,29 +376,30 @@ const side = {
                 },
                 {
                   "text": "设置 hosts 文件",
-                  "link":"/zh/manual/olares/settings/set-up-hosts",
+                  "link": "/zh/manual/olares/settings/set-up-hosts",
                 },
               ],
-             },
-            {text: "管理 GPU", link: "/zh/manual/olares/settings/gpu-resource"},
-            {text: "视频设置", link: "/zh/manual/olares/settings/video"},
+            },
+            { text: "管理 GPU", link: "/zh/manual/olares/settings/gpu-resource" },
+            { text: "视频设置", link: "/zh/manual/olares/settings/video" },
+            { text: "文件搜索", link: "/zh/manual/olares/settings/search" },
             {
               "text": "备份与恢复",
               "collapsed": true,
               "items": [
-                {text: "备份", link: "/zh/manual/olares/settings/backup"},
-                {text: "恢复", link: "/zh/manual/olares/settings/restore"},
+                { text: "备份", link: "/zh/manual/olares/settings/backup" },
+                { text: "恢复", link: "/zh/manual/olares/settings/restore" },
               ],
             },
-            {text: "开发者资源", link: "/zh/manual/olares/settings/developer"},
-            ]
-          },
+            { text: "开发者资源", link: "/zh/manual/olares/settings/developer" },
+          ]
+        },
         { "text": "仪表盘", "link": "/zh/manual/olares/resources-usage" },
         { "text": "Profile", "link": "/zh/manual/olares/profile" }
       ]
     },
     {
-      text: "Olares 进阶",
+      text: "教程",
       collapsed: true,
       link: "/zh/manual/best-practices/",
       items: [
@@ -368,11 +422,15 @@ const side = {
         {
           text: "在启用显卡直通的 PVE 上安装 Olares",
           link: "/zh/manual/best-practices/install-olares-gpu-passthrough",
-        },        
-        {  
+        },
+        {
           text: "在 Olares 中扩展存储空间",
           link: "/zh/manual/best-practices/expand-storage-in-olares",
         },
+        {
+          text: "本地访问 Olares",
+          link: "/manual/best-practices/local-access",
+        },
       ],
     },
     { text: "术语", link: "/zh/manual/glossary" },
@@ -425,7 +483,7 @@ const side = {
   ],
   "/zh/use-cases/": [
     {
-      text: "Tutorials & use cases",
+      text: "应用示例",
       link: "/zh/use-cases/",
       items: [
         {
@@ -469,12 +527,22 @@ const side = {
         },
         {
           text: "Steam",
-          link: "/zh/use-cases/stream-game",
-        },
-        {
-          text: "Redroid",
-          link: "/zh/use-cases/host-cloud-android",
+          collapsed: true,
+          items: [
+            {
+              text: "在 Olares 本机游玩",
+              link: "/zh/use-cases/play-games-directly",
+            },
+            {
+              text: "串流到其他设备",
+              link: "/zh/use-cases/stream-game",
+            }
+          ]
         },
+        // {
+        //   text: "Redroid",
+        //   link: "/zh/use-cases/host-cloud-android",
+        // },
       ],
     },
   ],
@@ -484,7 +552,8 @@ const side = {
       link: "/zh/developer/concepts/",
       items: [
         { text: "系统架构", link: "/zh/developer/concepts/system-architecture" },
-        { text: "Olares ID",
+        {
+          text: "Olares ID",
           link: "/zh/developer/concepts/olares-id",
           collapsed: true,
           items: [
@@ -543,76 +612,56 @@ const side = {
         },
         {
           text: "Olares CLI",
-          collapsed: true,
           link: "/zh/developer/install/cli/olares-cli",
+          collapsed: true,
           items: [
-            {text: "gpu", link: "/zh/developer/install/cli/gpu"},
-            {text: "osinfo", link: "/zh/developer/install/cli/osinfo"},
-            {text: "node", link: "/zh/developer/install/cli/node"},
             {
               text: "backups",
               link: "/zh/developer/install/cli/backups",
               collapsed: true,
               items: [
-                {text: "download", link: "/zh/developer/install/cli/backups-download"},
-                {text: "region", link: "/zh/developer/install/cli/backups-region"},
-                {text: "backup", link: "/zh/developer/install/cli/backups-backup"},
-                {text: "restore", link: "/zh/developer/install/cli/backups-restore"},
-                {text: "snapshots", link: "/zh/developer/install/cli/backups-snapshots"},
-                ],
-          },
-          {
-            text: "change-ip",
-            link: "/zh/developer/install/cli/change-ip",
-          },
-          {
-            text: "download",
-            link: "/zh/developer/install/cli/download",
-          },
-          { text: "info", link: "/zh/developer/install/cli/info" },
-          {
-            text: "install",
-            link: "/zh/developer/install/cli/install",
-          },
-          {
-            text: "user activate",
-            link: "/zh/developer/install/cli/user-activate",
-          },
-          {
-            text: "logs",
-            link: "/zh/developer/install/cli/logs",
-          },
-          {
-            text: "precheck",
-            link: "/zh/developer/install/cli/precheck",
-          },
-          {
-            text: "prepare",
-            link: "/zh/developer/install/cli/prepare",
-          },
-          {
-            text: "release",
-            link: "/zh/developer/install/cli/release",
-          },
-          {
-            text: "start",
-            link: "/zh/developer/install/cli/start",
-          },
-          {
-            text: "stop",
-            link: "/zh/developer/install/cli/stop",
-          },
-          {
-            text: "uninstall",
-            link: "/zh/developer/install/cli/uninstall",
-          },
-        ],
-      },
-            
+                { text: "backup", link: "/zh/developer/install/cli/backups-backup" },
+                { text: "download", link: "/zh/developer/install/cli/backups-download" },
+                { text: "region", link: "/zh/developer/install/cli/backups-region" },
+                { text: "restore", link: "/zh/developer/install/cli/backups-restore" },
+                { text: "snapshots", link: "/zh/developer/install/cli/backups-snapshots" },
+              ],
+            }, 
+            { text: "change-ip", link: "/zh/developer/install/cli/change-ip" },
+            { text: "disk", link: "/zh/developer/install/cli/disk" },   
+            { text: "download", link: "/zh/developer/install/cli/download" },
+            { text: "gpu", link: "/zh/developer/install/cli/gpu" },
+            { text: "info", link: "/zh/developer/install/cli/info" },         
+            { text: "install", link: "/zh/developer/install/cli/install" },
+            { text: "logs", link: "/zh/developer/install/cli/logs" },
+            { text: "node", link: "/zh/developer/install/cli/node" },
+            { text: "osinfo", link: "/zh/developer/install/cli/osinfo" },
+            { text: "precheck", link: "/zh/developer/install/cli/precheck" },
+            { text: "prepare", link: "/zh/developer/install/cli/prepare" },
+            { text: "release", link: "/zh/developer/install/cli/release" },
+            { text: "start", link: "/zh/developer/install/cli/start" },
+            { text: "stop", link: "/zh/developer/install/cli/stop" },
+            { text: "uninstall", link: "/zh/developer/install/cli/uninstall" },
+            { text: "upgrade", link: "/zh/developer/install/cli/upgrade" },
             {
-              text: "版本说明",
-              link: "/zh/developer/install/versioning",
+              text: "user",
+              link: "/zh/developer/install/cli/user",
+              collapsed: true,
+              items: [
+                { text: "activate", link: "/zh/developer/install/cli/user-activate" },
+                { text: "create", link: "/zh/developer/install/cli/user-create" },
+                { text: "delete", link: "/zh/developer/install/cli/user-delete" },
+                { text: "get", link: "/zh/developer/install/cli/user-get" },
+                { text: "list", link: "/zh/developer/install/cli/user-list" },
+                { text: "reset-password", link: "/zh/developer/install/cli/user-reset-password" },
+              ],
             },
+          ],
+        },
+        {
+          text: "版本说明",
+          link: "/zh/developer/install/versioning",
+        },
       ],
     },
     {
@@ -654,7 +703,7 @@ const side = {
               text: "OlaresManifest",
               link: "/zh/developer/develop/package/manifest",
             },
-            /*/{
+            /*{
               text: "推荐算法",
               link: "/zh/developer/develop/package/recommend",
             },*/
@@ -664,66 +713,66 @@ const side = {
             },
           ],
         },
-      //  {
+        //  {
         //      text: "进阶",
         //     collapsed: true,
         //    items: [
         //      {
         //        text: "terminus-info",
-      //       link: "/zh/developer/develop/advanced/terminus-info",
+        //       link: "/zh/developer/develop/advanced/terminus-info",
         //      },
         //      {
         //       text: "Service Provider",
-      //       link: "/zh/developer/develop/advanced/provider",
+        //       link: "/zh/developer/develop/advanced/provider",
         //      },
         //     {
         //       text: "AI",
-      //       link: "/zh/developer/develop/advanced/ai",
+        //       link: "/zh/developer/develop/advanced/ai",
         //     },
         //      { text: "Cookie", link: "/zh/developer/develop/advanced/cookie" },
         //      { text: "数据库", link: "/zh/developer/develop/advanced/database" },
         //     {
         //       text: "账户",
-      //       link: "/zh/developer/develop/advanced/account",
+        //       link: "/zh/developer/develop/advanced/account",
         //      },
         //      {
         //       text: "应用市场",
-      //       link: "/zh/developer/develop/advanced/market",
+        //       link: "/zh/developer/develop/advanced/market",
         //      },
-            // {
-            //   text: "Analytic",
-            //   link: "/zh/developer/develop/advanced/analytic",
-            // },
+        // {
+        //   text: "Analytic",
+        //   link: "/zh/developer/develop/advanced/analytic",
+        // },
         //       {
         //        text: "Websocket",
-      //        link: "/zh/developer/develop/advanced/websocket",
+        //        link: "/zh/developer/develop/advanced/websocket",
         //      },
         //      {
         //        text: "文件上传",
-      //       link: "/zh/developer/develop/advanced/file-upload",
-      //      },
-            // {
-            //   text: "Rss",
-            //   link: "/zh/developer/develop/advanced/rss",
-            // },
-    //      {
-    //         text: "密钥",
-      //         link: "/zh/developer/develop/advanced/secret",
+        //       link: "/zh/developer/develop/advanced/file-upload",
+        //      },
+        // {
+        //   text: "Rss",
+        //   link: "/zh/developer/develop/advanced/rss",
+        // },
+        //      {
+        //         text: "密钥",
+        //         link: "/zh/developer/develop/advanced/secret",
+        //      },
+        // {
+        //   text: "Notification",
+        //   link: "/zh/developer/develop/advanced/notification",
+        // },
+        // {
+        //   text: "Frontend",
+        //   link: "/zh/developer/develop/advanced/frontend",
+        // },
+        //        {
+        //          text: "Kubesphere",
+        //          link: "/zh/developer/develop/advanced/kubesphere",
+        //         },
+        //       ],
         //      },
-            // {
-            //   text: "Notification",
-            //   link: "/zh/developer/develop/advanced/notification",
-            // },
-            // {
-            //   text: "Frontend",
-            //   link: "/zh/developer/develop/advanced/frontend",
-            // },
-    //        {
-    //          text: "Kubesphere",
-    //          link: "/zh/developer/develop/advanced/kubesphere",
-    //         },
-    //       ],
-    //      },
         {
           text: "提交应用",
           collapsed: true,
@@ -842,8 +891,8 @@ const side = {
         },
       ],
     },
-    ],
-  };
+  ],
+};
 
 export const zh = defineConfig({
   lang: "zh",
@@ -860,4 +909,4 @@ export const zh = defineConfig({
 
     sidebar: side,
   },
-});
+});

docs/developer/concepts/application.md

@@ -122,7 +122,7 @@ The mechanism consists of three procedures：
 
 - User
 
-  [Manage apps in Market](../../manual/olares/market.md)<br>
+  [Manage apps in Market](../../manual/olares/market/market.md)<br>
 
 - Developer
 

docs/developer/develop/submit/index.md

@@ -17,7 +17,7 @@ outline: [2, 3]
 ### 1. Develop and test your application
 
 Before submitting an application, please ensure that it has been thoroughly tested on your Olares.
-- Use Studio's dev-container to test and debug your application in a real online environment. [Learn more about Studio](../tutorial/).
+- Use Studio's dev-container to test and debug your application in a real online environment. [Learn more about Studio](../tutorial/develop.md).
 - Use the [custom installation](../tutorial/package-upload.md) in the Market app for user testing.
 
 ### 2. Submit an application

docs/developer/develop/tutorial/develop.md

@@ -92,13 +92,13 @@ This example demonstrates creating a basic web page manually.
    ```
 5. Create a file named `index.js` in `/root/` with the following content:
    ```js
-    // Ensure the port matches what you defined
-    const express = require('express');
-    const app = express();
-    app.use(express.static('public/'));
-    app.listen(8080), function() {
-        console.log('Server is running on port 8080');
-    };
+   // Ensure the port matches what you defined
+   const express = require('express');
+   const app = express();
+   app.use(express.static('public/'));
+   app.listen(8080, function() {
+       console.log('Server is running on port 8080');
+   });
    ```
 6. Create a `public` directory in `/root/` and add an `index.html` file:
    ```html
@@ -204,15 +204,15 @@ Once deployed, go to **Services** > **Ports**. You can see your new port listed
    const express = require('express');
    const app = express();
    app.use(express.static('public/'));
-   app.listen(8080), function() {
-   console.log('Server is running on port 8080');
-   };
+   app.listen(8080, function() {
+       console.log('Server is running on port 8080');
+   });
    // Add the following
    const app_new = express();
    app_new.use(express.static('new/'));
-   app_new.listen(8081), function() {
-   console.log('Server is running on port 8081');
-   };
+   app_new.listen(8081, function() {
+       console.log('Server is running on port 8081');
+   });
    ```
 2. Create a `new` directory in `/root/` and add an `index.html` file:
    ```html

docs/developer/install/cli/backups-backup.md

@@ -65,7 +65,7 @@ These options apply to all backends:
   kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}'
   ```
 
-## Example
+## Examples
 ```bash
 # Backup to Tencent COS
 olares-cli backups backup cos --path /data --repo-name my_repo \

docs/developer/install/cli/backups-download.md

@@ -12,7 +12,7 @@ olares-cli backups download [options]
 |--------------------|-----------|--------------------------------------------------------|-------------------------|--------------------|
 | `--download-cdn-url`|           | Specifies the CDN URL for downloading the Restic tool. | No                   | System default URL |
 | `--help`           | `-h`      | Displays help information.                             | No                   | N/A                |
-## Example
+## Examples
 ```bash d
 # Download Restic using a custom CDN URL
 olares-cli backups download --download-cdn-url https://custom-cdn.example.com/restic

docs/developer/install/cli/backups-region.md

@@ -17,7 +17,7 @@ olares-cli backups region space [options]
 
 1. To retrieve the access token and Olares DID, inspect the payload of the network requests made by the Olares Space web interface after logging in. The `token` field corresponds to the access token, and the `userid` field corresponds to the Olares DID.
 
-## Example
+## Examples
 ```bash
 # Query cloud name and region ID
 olares-cli backups region space \

docs/developer/install/cli/backups-restore.md

@@ -69,7 +69,7 @@ These options apply to all backends:
   kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}'
   ```
 
-## Example
+## Examples
 ```bash
 # Restore the data from Tencent COS
 olares-cli backups restore cos --path /data_restore --repo-name my_repo \

docs/developer/install/cli/backups-snapshots.md

@@ -61,7 +61,7 @@ These options apply to all backends:
   kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}'
   ```
 
-## Example
+## Examples
 ```bash
 # List snapshots for Tencent COS
 olares-cli backups snapshots cos --repo-name my_repo \

docs/developer/install/cli/disk.md

@@ -0,0 +1,33 @@
+# `disk`
+
+## Synopsis
+
+The `disk` command provides a set of tools to manage storage resources in the Olares system. It is specifically used for managing LVM-based storage configurations.
+
+
+```bash
+olares-cli disk <subcommand>
+```
+
+## Subcommands
+
+| Subcommand | Description | 
+|--|--|
+| `extend` | Extends Olares storage capacity on LVM-based installations. |
+| `list-unmounted` | Lists unmounted disks. |
+
+## Options
+
+| Name | Shorthand | Usage | 
+|--|--|--|
+| `--help` | `-h` | Displays help information.|
+
+## Examples
+
+```bash
+# List all disks that are connected but not mounted
+olares-cli disk list-unmounted
+
+# Extend Olares storage by adding newly detected unmounted disks
+olares-cli disk extend
+```

docs/developer/install/cli/gpu.md

@@ -32,7 +32,7 @@ olares-cli gpu <subcommand> [options]
 | `--version`| `-v`      | Specifies the Olares version for GPU drivers and components. <br>Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).<br> Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No                   | Current version    |
 | `--help`   | `-h`      | Displays help information.                                                                                                                                                                                                                                                         | No                   | N/A                            |
 
-## Example
+## Examples
 
 ```bash
 # Install GPU drivers and dependencies to a specific directory

docs/developer/install/cli/info.md

@@ -7,7 +7,7 @@ The `info` command displays general information about the installed Olares versi
 olares-cli info
 ```
 
-## Flag
+## Options
 
 | Name     | Shorthand | Usage                     |
 |----------|-----------|---------------------------|

docs/developer/install/cli/logs.md

@@ -28,7 +28,7 @@ olares-cli logs [option]
 | `--output-dir`         |           | Saves logs to the specified directory. Creates the directory if it does not exist.                                                                                                                 | No                   | `./olares-logs`                |
 | `--since`              |           | Fetches logs newer than a specified relative duration (e.g., `5s`, `2m`, `3h`).                                                                                                                    | No                   | `7d`                           |
 
-## Example
+## Examples
 ```bash
 # Collect all logs with default settings
 olares-cli logs

docs/developer/install/cli/node.md

@@ -29,7 +29,7 @@ olares-cli node <subcommand> [options]
 | `--version`                     | `-v`      | Specifies the Olares version. <br>Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).<br> Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No                   | Current version    |
 | `--help`                        | `-h`      | Displays help information.                                                                                                                                                                                                                                | No                   | N/A                            |                                                        |
 
-## Example
+## Examples
 
 ```bash
 # Retrieve system information from a master node at IP 192.168.1.15

docs/developer/install/cli/olares-cli.md

@@ -28,12 +28,13 @@ wsl -d Ubuntu
 ## Syntax
 The Olares CLI uses the following syntax:
 
-> `olares-cli command [subcommand] [option]`
+> `olares-cli command [subcommand] [argument] [options] `
 
 where
 - `command`: Specifies the main operation you want to perform. For example, `olares-cli install`.
 - `subcommand`: Further specifies the task for commands that support additional operations. For example, `wizard` or `component`.
-- `option`: Optional arguments that modify the behavior of the `command`. Options include flags and options with arguments.
+- `argument`: Specifies the target resource or input data for the command, typically an ID, name, or file path. For example, in `olares-cli user activate <Olares ID> [options]`, `<Olares ID>` is the argument.
+- `options`: Optional arguments that modify the behavior of the `command`. Options include flags and options with arguments.
 
 Olares CLI allows you to temporarily override certain Olares default settings. Each option applies only to the command in which it is used.
 
@@ -43,21 +44,23 @@ To get detailed help for any command, run `olares-cli help`.
 
 ## Available CLI commands
 
-| Operation          | Syntax                                             | Description                                                                                                                  |
-|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
-| `gpu`              | `olares-cli gpu <subcommand> [option]`             | Manages GPU-related operations.                                                                                              |
-| `info`             | `olares-cli info <subcommand> [option]`     | Displays general information about the operating system of the current device.                                               |
-| `node`             | `olares-cli node <subcommand> [option]`            | Manages node-related operations.                                                                                             |
-| `backups`   | `olares-cli backups <subcommand> [option]`  | Manages backup-related operations.                                                                                           |
-| `change-ip` | `olares-cli change-ip [option]`             | Changes the IP address of the Olares OS.                                                                                     |
-| `download`  | `olares-cli download <subcommand> [option]` | Downloads specific resources.                                                                                                |
-| `info`      | `olares-cli info [option]`                  | Displays general information about the downloaded Olares OS.                                                                 |
-| `install`   | `olares-cli install [option]`               | Deploys system-level and user-level components of Olares.                                                                    |
-| `logs`      | `olares-cli logs [option]`                  | Collects logs from Olares system components for debugging and troubleshooting.                                               |
-| `precheck`  | `olares-cli precheck [option]`              | Verifies whether the system environment meets all requirements for Olares installation.                                      |
-| `prepare`   | `olares-cli prepare [option]`               | Prepares the environment for the installation process, including setting up essential services and configurations of Olares. |
-| `release`   | `olares-cli release [option]`               | Packages Olares installation resources for distribution or deployment.                                                       |
-| `start`     | `olares-cli start [option]`                 | Starts Olares services and components.                                                                                       |
-| `stop`      | `olares-cli stop [option]`                  | Stops Olares services and components.                                                                                        |
-| `uninstall` | `olares-cli uninstall [option]`             | Uninstalls Olares completely, or roll back the installation to a specific phase.                                             |
-
+| Operation  | Syntax   | Description     |
+|--|--|--|
+| `backups` | `olares-cli backups <subcommand> [options]` | Manages backup-related operations.  |
+| `change-ip` | `olares-cli change-ip [options]` | Changes the IP address of the Olares OS.  |
+| `disk` | `olares-cli disk <subcommand>` | Manages storage resources in the Olares system. |
+| `download`  | `olares-cli download <subcommand> [options]` | Downloads specific resources. |
+| `gpu` | `olares-cli gpu <subcommand> [options]`  | Manages GPU-related operations. |
+| `info` | `olares-cli info [options]` | Displays general information about the downloaded Olares OS. |
+| `install`  | `olares-cli install [options]`  | Deploys system-level and user-level components of Olares. |
+| `logs` | `olares-cli logs [options]` | Collects logs from Olares system components for debugging and troubleshooting.  |
+| `node`  | `olares-cli node <subcommand> [options]` | Manages node-related operations. |
+| `osinfo`   | `olares-cli osinfo <subcommand> [options]`  | Displays general information about the operating system of the current device. |
+| `precheck`  | `olares-cli precheck [options]` | Verifies whether the system environment meets all requirements for Olares installation.  |
+| `prepare`  | `olares-cli prepare [options]` | Prepares the environment for the installation process, including setting up essential services and configurations of Olares. |
+| `release`   | `olares-cli release [options]` | Packages Olares installation resources for distribution or deployment.  |
+| `start`  | `olares-cli start [options]` | Starts Olares services and components. |
+| `stop` | `olares-cli stop [options]` | Stops Olares services and components.  |
+| `uninstall` | `olares-cli uninstall [options]` | Uninstalls Olares completely, or roll back the installation to a specific phase. |
+| `upgrade` | `olares-cli upgrade <subcommand> [options]` | Upgrades Olares and checks upgrade readiness and compatibility.|
+| `user` | `olares-cli user <subcommand> [options]`| Manages users in the Olares system |

docs/developer/install/cli/osinfo.md

@@ -8,13 +8,13 @@ The `osinfo` command provides detailed information about the operating system of
 olares-cli osinfo <subcommand> [options]
 ```
 
-## Subcommand
+## Subcommands
 
 | Subcommand | Description                                                          |
 |------------|----------------------------------------------------------------------|
 | `show`     | Prints information about the operating system of the current device. |
 
-## Flag
+## Options
 
 | Name         | Short | Description                                                                                                                                                                                                                                                                              |
 |--------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/developer/install/cli/prepare.md

@@ -18,7 +18,7 @@ olares-cli prepare [option]
 | `--version`        | `-v`      | Specifies the Olares version. <br>Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).<br> Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No                   | Current version |
 
 
-## Example
+## Examples
 ```bash
 # Uses JuiceFS as the root filesystem
 olares-cli prepare --with-juicefs=true

docs/developer/install/cli/start.md

@@ -12,7 +12,7 @@ olares-cli start [option]
 After executing this command, allow 5-8 minutes for all Olares components to restart. You can verify the status of all pods by running `kubectl get pods -A` or by simply trying to access your Olares desktop.
 :::
 
-## Option
+## Options
 
 | Name             | Shorthand | Usage                                                                                                                                                                                                                                                     |
 |------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/developer/install/cli/stop.md

@@ -15,7 +15,7 @@ olares-cli stop [option]
 | `--help`           | `-h`      | Displays help information.                                                                                | No                   | N/A     |
 | `--timeout`        |           | Sets the maximum time to wait for a graceful shutdown before using SIGKILL (e.g., `5s`, `2m`, `3h`).       | No                   | `1m`    |
 
-## Example
+## Examples
 ```bash
 # Stop the Olares system
 olares-cli stop

docs/developer/install/cli/upgrade.md

@@ -0,0 +1,53 @@
+# `upgrade`
+
+## Synopsis
+
+The `upgrade` command provides a set of tools for upgrading Olares and checking upgrade readiness and compatibility.
+
+```bash
+olares-cli upgrade <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Aliases | Description | 
+|--|--|--|
+| `precheck` | | Prechecks Olares for upgrade. |
+| `spec` | `current-spec` | Gets the upgrade spec of the current CLI version. |
+| `viable` | | Determines whether upgrade can be directly performed upon a base version. |
+
+## Global options
+
+These options apply to the main `upgrade` command and are inherited by its subcommands where applicable.
+
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--base-dir` | `-b` | Sets the base directory for Olares packages. | No | `$HOME/.olares` |
+| `--help` | `-h` | Displays help information. | No | N/A |
+| `--version` | `-v` | Sets the target Olares version to upgrade to. For example, `1.10.0`, `1.10.0-20241109`. | No | N/A |
+
+## Options for `viable`
+
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--base` | `-b` | Base version to check. | No | Current Olares system version |
+
+:::warning Option conflict 
+The `-b` shorthand is used by the parent command for `--base-dir`. However, when running `upgrade viable`, `-b` specifically refers to `--base`. 
+:::
+
+## Examples
+
+```bash
+# Check whether the current system can be upgraded directly
+olares-cli upgrade viable
+
+# Check upgrade viability from a specific base version
+olares-cli upgrade viable --base 1.9.0
+
+# Run pre-upgrade checks
+olares-cli upgrade precheck
+
+# View the upgrade spec of the current CLI
+olares-cli upgrade spec
+```

docs/developer/install/cli/user-activate.md

@@ -1,8 +1,9 @@
-# `user activate`
+# `activate`
 
 ## Synopsis
 
-The `user activate` command activates an existing Olares account. It requires the user's Olares ID, password, and 12-word mnemonic phrase to complete the activation. This command typically requires administrator privileges (`sudo`).
+The `activate` subcommand activates an existing Olares account. It requires the user's Olares ID, password, and 12-word mnemonic phrase to complete the activation. 
+
 
 ```bash
 olares-cli user activate <Olares ID> [options]
@@ -12,31 +13,32 @@ olares-cli user activate <Olares ID> [options]
 
 | Argument | Description | Required|
 |--|--|--|
-| `<Olares ID>` | Specifies the unique identifier for the Olares user account to be activated. <br>Similar to an email address(e.g., `alice123@olares.com`).| **Yes** |
+| `<Olares ID>` | Specifies the unique identifier for the Olares user account <br>to be activated. <br>Similar to an email address like `alice123@olares.com`.| Yes |
 
 ## Options
-| Option | Shorthand | Usage | Required | Default |
+| Option | Short| Usage | Required | Default |
 |--|--|--|--|--|
-| `--bfl` | | Specifies the Backend For Launcher (BFL) service URL (e.g., `https://example.com`). | No | `http://127.0.0.1:30180` |
+| `--bfl` | | Specifies the Backend For Launcher (BFL) service URL, such as `https://example.com`. | No | `http://127.0.0.1:30180` |
 | `--enable-tunnel` | | Enables or disables tunnel mode for activation. | No | `false` |
 | `--help` | `-h` | Displays help information. | No | N/A |
-| `--host` | | Specifies the Fast Reverse Proxy (FRP) host. <br>Only used when the `--enable-tunnel` option is set to `true`. | No | N/A |
-| `--jws` | | Specifies the FRP JWS token.<br>Only used when the `--enable-tunnel` option is set to `true`.| No | N/A |
+| `--host` | | Specifies the Fast Reverse Proxy (FRP) host. Only used when `--enable-tunnel` option is set to `true`. | No | N/A |
+| `--jws` | | Specifies the FRP JWS token. Only used when `--enable-tunnel` option is set to `true`.| No | N/A |
 | `--language` | | Sets the system language. | No | `en-US` |
 | `--location` | | Sets the timezone location. | No | `Asia/Shanghai` |
-| `--mnemonic` | | Specifies the 12-word mnemonic phrase required for activation. | **Yes** | N/A |
-| `--password` | `-p` | Specifies the Olares login password for authentication.	 | **Yes** | N/A |
-| `--vault` | | Specifies the Vault service URL (e.g., `https://example.com`). | No | `http://127.0.0.1:30181` |
+| `--mnemonic` | | Specifies the 12-word mnemonic phrase required for activation. | Yes | N/A |
+| `--password` | `-p` | Specifies the Olares login password for authentication.	 | Yes | N/A |
+| `--reset-password` | | Specifies the new password to set during password reset. This option is required only when performing a password reset. | No | N/A |
+| `--vault` | | Specifies the Vault service URL, such as `https://example.com`. | No | `http://127.0.0.1:30180` |
 
-## Example
+## Examples
 
 ```bash
 # Activate an Olares user account
-sudo olares-cli user activate alice@olares.com -p "HerPassWord"  --mnemonic "apple banana cherry door eagle forest grape house island jacket kite lemon"
+olares-cli user activate alic123e@olares.com -p "HerPassWord"  --mnemonic "apple banana cherry door eagle forest grape house island jacket kite lemon"
 
 # Activate an Olares user account with tunnel mode enabled
-sudo olares-cli user activate david@olares.com -p "HisPassWord"  --enable-tunnel --host "frp-gateway.olares.com"  --jws "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.demo.signature"  --bfl http://127.0.0.1:30180 --vault http://127.0.0.1:30180/server  --mnemonic "apple banana cherry door eagle forest grape house island jacket kite lemon"
+olares-cli user activate david456@olares.com -p "HisPassWord"  --enable-tunnel --host "frp-gateway.olares.com"  --jws "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.demo.signature"  --bfl http://127.0.0.1:30180 --vault http://127.0.0.1:30180/server  --mnemonic "apple banana cherry door eagle forest grape house island jacket kite lemon"
 
 # Activate an Olares user account with specific language and timezone settings
-sudo olares-cli user activate carol@olares.com -p "AnotherPassWord"  --mnemonic "alpha beta gamma delta epsilon zeta eta theta iota kappa lambda mu"  --language "en-US" --location "America/New_York"
+olares-cli user activate carol789@olares.com -p "AnotherPassWord"  --mnemonic "alpha beta gamma delta epsilon zeta eta theta iota kappa lambda mu"  --language "en-US" --location "America/New_York"
 ```

docs/developer/install/cli/user-create.md

@@ -0,0 +1,46 @@
+# `create`
+
+## Synopsis
+
+The `create` subcommand creates a new user account in the Olares system. It allows administrators to define initial settings such as the username, password, role permissions, and resource limits. 
+
+**Aliases**: `create`, `add`, `new`
+
+```bash
+olares-cli user create <name> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required|
+|--|--|--|
+| `<name>` | Specifies the username for the new account. <br>It is typically the part before the `@` symbol in an Olares ID. <br>For example, `alice123` for `alice123@olares.com`.| Yes |
+
+## Options
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--cpu-limit` | `-c` | Sets the CPU limit for the user environment. | No | `1` |
+| `--description` | | Adds a description for the user account. | No | N/A |
+| `--display-name` | | Sets the display name for the user. | No | N/A |
+| `--domain` | | Specifies the domain for the Olares ID. | No | Olares system's domain |
+| `--help` | `-h` | Displays help information. | No | N/A |
+| `--kubeconfig` | | Specifies the path to a kubeconfig file. | No | N/A |
+| `--memory-limit` | `-m` | Sets the memory limit for the user environment. | No | `3G` |
+| `--password` | `-p` | Sets the initial login password for the user. | No | N/A |
+| `--role` | `-r` | Sets the user role.<br>Valid values: `owner`, `admin`, `normal`. | No | `normal` |
+
+## Examples
+
+```bash
+# Create a basic user with default settings
+olares-cli user create alice123
+
+# Create a user with a specified password and role
+olares-cli user create blake123 -p "StrongPassword123" -r admin
+
+# Create a user with custom resource limits (2 CPU cores, 4 GB memory)
+olares-cli user create carol123 --cpu-limit 2 --memory-limit 4G
+
+# Create a user with display name and description
+olares-cli user create david123 --display-name "David Smith" --description "Data platform administrator"
+```

docs/developer/install/cli/user-delete.md

@@ -0,0 +1,30 @@
+# `delete`
+
+## Synopsis
+
+The `delete` subcommand permanently removes an existing user account from the Olares system. 
+
+**Aliases**: `delete`, `d`, `del`, `rm`, `remove`
+
+```bash
+olares-cli user delete <name> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required|
+|--|--|--|
+| `<name>` | Specifies the username of the account to be deleted. <br>It is typically the part before the `@` symbol in an Olares ID. <br>For example, `alice123` for `alice123@olares.com`.| Yes |
+
+## Options
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--help` | `-h` | Displays help information. | No | N/A |
+| `--kubeconfig` | | Specifies the path to a kubeconfig file. | No | N/A |
+
+## Examples
+
+```bash
+# Delete a user named alice123
+olares-cli user delete alice123
+```

docs/developer/install/cli/user-get.md

@@ -0,0 +1,33 @@
+# `get`
+
+## Synopsis
+
+The `get` subcommand retrieves detailed information about a specific Olares user account. The output can be formatted as a table or JSON. 
+
+```bash
+olares-cli user get <name> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required|
+|--|--|--|
+| `<name>` | Specifies the username of the account to retrieve. <br>It is typically the part before the `@` symbol in an Olares ID. <br>For example, `alice123` for `alice123@olares.com`.| Yes |
+
+## Options
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--help` | `-h` | Displays help information. | No | N/A |
+| `--kubeconfig` | | Specifies the path to a kubeconfig file. | No | N/A |
+| `--no-headers` | | Disables the header row in the output. | No | N/A |
+| `--output` | `-o` | Specifies the output format. Valid values: `table`, `json`. | No | `table` |
+
+## Examples
+
+```bash
+# Get details for user named alice123 in default table format
+olares-cli user get alice123
+
+# Get details for user named blake123 in JSON format
+olares-cli user get blake123 -o json
+```

docs/developer/install/cli/user-list.md

@@ -0,0 +1,34 @@
+# `list`
+
+## Synopsis
+
+The `list` subcommand displays a list of all registered users in the Olares system. You can sort, filter, and format the output to suit your needs. 
+
+**Aliases**: `list`, `ls`, `l`
+
+```bash
+olares-cli user list [options]
+```
+
+## Options
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+| `--help` | `-h` | Displays help information. | No | N/A |
+| `--kubeconfig` | | Specifies the path to a kubeconfig file. | No | N/A |
+| `--no-headers` | | Disables the header row in the output. | No | N/A |
+| `--output` | `-o`| Specifies the output format. Valid values: `table`, `json`.| No | `table` |
+| `--reverse` | `-r` | Reverses the sort order of the output. | No | N/A |
+| `--sort` | | Sorts the output by a specific field.<br> Valid values: `name`, `role`, `create-time`, `memory`, `cpu` | No | N/A |
+
+## Examples
+
+```bash
+# List all users in a table format
+olares-cli user list
+
+# List all users in JSON format
+olares-cli user list -o json
+
+# List users sorted by role
+olares-cli user list --sort role
+```

docs/developer/install/cli/user-reset-password.md

@@ -0,0 +1,29 @@
+# `reset-password`
+
+## Synopsis
+
+The `reset-password` subcommand forcefully resets the login password for a specific user via the authentication provider.
+
+```bash
+olares-cli user reset-password <username> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required|
+|--|--|--|
+| `<username>` | Specifies the username of the account to reset. <br>It is typically the part before the `@` symbol in an Olares ID. <br>For example, `alice123` for `alice123@olares.com`.| Yes |
+
+## Options
+| Option | Shorthand | Usage | Required | Default |
+|--|--|--|--|--|
+ `--help` | `-h` | Displays help information. | No | N/A |
+| `--kubeconfig` | | Specifies the path to a kubeconfig file. | No | N/A |
+| `--password` | `-p` | Specifies the new password for the user. | Yes | N/A |
+
+## Examples
+
+```bash
+# Reset password for user named alice123
+olares-cli user reset-password alice123 -p "NewSecurePassword456!"
+```

docs/developer/install/cli/user.md

@@ -0,0 +1,13 @@
+# `user`
+The `user` command provides a set of tools to manage users in the Olares system. It allows administrators to create, activate, query, and remove users, as well as reset user passwords.
+
+## Subcommands
+
+| Subcommand  | Description |
+|--|--|
+| `activate` | Activates an existing Olares account. |
+| `create` | Creates a new user. |
+| `delete` | Deletes an existing user. |
+| `get` | Retrieves details of a specific user. |
+| `list` | Lists all users within the Olares cluster. |
+| `reset-password` | Forcefully resets a user's password via the authentication provider. |

docs/developer/install/environment-variables.md

@@ -34,20 +34,6 @@ Specifies whether to enable the Cloudflare proxy.
   - `1` (enable)
 - **Default**: `0`
 
-### `DID_GATE_URL`
-Specifies the endpoint for the DID gateway.
-- **Valid values**:
-  - `https://did-gate-v3.bttcdn.com`
-  - `https://did-gate-v3.api.jointerminus.cn/` (recommended for better connectivity in mainland China)
-- **Default**: `https://did-gate-v3.bttcdn.com`
-
-### `FIREBASE_PUSH_URL`
-Specifies the endpoint for Firebase push services.
-- **Valid values**:
-  - `https://firebase-push-test.bttcdn.com/v1/api/push`
-  - `https://firebase-push-test.api.jointerminus.cn/v1/api/push` (recommended for better connectivity in mainland China)
-- **Default**: `https://firebase-push-test.bttcdn.com/v1/api/push`
-
 ### `FRP_AUTH_METHOD`
 Sets the FRP authentication method.
 - **Valid values**:
@@ -68,13 +54,6 @@ Specifies whether to enable FRP for internal network tunneling. Requires additio
   - `1` (enable)
 - **Default**: `0`
 
-### `FRP_LIST_URL`
-Specifies the endpoint for the Olares FRP information service.
-- **Valid values**:
-  - `https://terminus-frp.snowinning.com`
-  - `https://terminus-frp.api.jointerminus.cn` (recommended for better connectivity in mainland China)
-- **Default**: `https://terminus-frp.snowinning.com`
-
 ### `FRP_PORT`
 Specifies the FRP server's listening port.
 - **Valid values**: An integer in the range `1–65535`
@@ -106,13 +85,6 @@ Specifies whether to enable GPU sharing. Applies only if GPU is enabled.
   - `1` (enable)
 - **Default**: `0`
 
-### `MARKET_PROVIDER`
-Specifies the backend domain used by the application marketplace (Market).
-- **Valid values**:
-  - `appstore-server-prod.bttcdn.com`
-  - `appstore-china-server-prod.api.jointerminus.cn` (recommended for better connectivity in mainland China)
-- **Default**: `appstore-server-prod.bttcdn.com`
-
 ### `NVIDIA_CONTAINER_REPO_MIRROR`
 Specifies the APT repository mirror for installing NVIDIA Container Toolkit.
 - **Valid values**:
@@ -120,13 +92,6 @@ Specifies the APT repository mirror for installing NVIDIA Container Toolkit.
   - `mirrors.ustc.edu.cn` (recommended for better connectivity in mainland China)
 - **Default**: `nvidia.github.io`
 
-### `OLARES_SPACE_URL`
-Specifies the endpoint for the Olares Space service.
-- **Valid values**:
-  - `https://cloud-api.bttcdn.com/`
-  - `https://cloud-api.api.jointerminus.cn/` (recommended for better connectivity in mainland China)
-- **Default**: `https://cloud-api.bttcdn.com/`
-
 ### `PREINSTALL`
 Runs only the pre-installation phase (system dependency setup) without proceeding to the full Olares installation.
 - **Valid values**: `1`
@@ -145,27 +110,6 @@ Specifies a custom Docker registry mirror for faster image pulls.
 - **Valid values**: `https://mirrors.olares.com` or any other valid URL
 - **Default**: `https://registry-1.docker.io`
 
-### `TAILSCALE_CONTROLPLANE_URL`
-Specifies the endpoint for the Olares Tailscale control-plane service.
-- **Valid values**:
-  - `https://controlplane.snowinning.com`
-  - `https://controlplane.api.jointerminus.cn` (recommended for better connectivity in mainland China)
-- **Default**: `https://controlplane.snowinning.com`
-
-### `TERMINUS_CERT_SERVICE_API`
-Specifies the endpoint for the Olares HTTPS certificate service.
-- **Valid values**:
-  - `https://terminus-cert.snowinning.com`
-  - `https://terminus-cert.api.jointerminus.cn` (recommended for better connectivity in mainland China)
-- **Default**: `https://terminus-cert.snowinning.com`
-
-### `TERMINUS_DNS_SERVICE_API`
-Specifies the endpoint for the Olares DNS service.
-- **Valid values**:
-  - `https://terminus-dnsop.snowinning.com`
-  - `https://terminus-dnsop.api.jointerminus.cn` (recommended for better connectivity in mainland China)
-- **Default**: `https://terminus-dnsop.snowinning.com`
-
 ### `TERMINUS_IS_CLOUD_VERSION`
 Marks the machine explicitly as a cloud instance.
 - **Valid values**: `true`

docs/manual/best-practices/index.md

@@ -1,12 +1,13 @@
 ---
 description: In-depth guides and proven best practices to help you get the most out of Olares.
 ---
-# Beyond the basics: Olares best practices and advanced guides
+# Tutorials
 
-This section offers in-depth guides and proven best practices to help you get the most out of Olares. Whether you're optimizing performance, securing your environment, or customizing advanced features, these resources go beyond initial setup to support real-world scenarios and power-user workflows.
+This section offers in-depth guides and proven best practices to help you get the most out of Olares.
 
 - [Configure a custom domain for your Olares](set-custom-domain.md)
 - [Install a multi-node Olares cluster](install-olares-multi-node.md)
 - [Build your knowledge hub with Wise](organize-content.md)
 - [Install Olares on PVE via ISO with GPU Passthrough](install-olares-gpu-passthrough.md)
 - [Expand Olares storage capacity](expand-storage-in-olares.md)
+- [Access Olares services locally](local-access.md)

docs/manual/best-practices/local-access.md

@@ -0,0 +1,250 @@
+---
+outline: [2,3]
+description: Learn the different methods to access Olares services locally for improved speed and offline capability.
+---
+# Access Olares services locally
+Olares is designed to provide seamless access to your self-hosted services anytime, anywhere.
+
+However, accessing your devices locally provides several advantages:
+- **Maximum performance**: Transfer files at full speed without the latency and potential bottlenecks of the internet.
+- **Enhanced privacy**: Keep your traffic contained within your home network for added security.
+- **Offline independence**: Access your data and apps even when your internet service is unavailable.
+
+## Objectives
+
+By the end of this tutorial, you will learn how to:
+
+- Establish a secure, high-speed local connection using the LarePass VPN.
+- Access Olares services using `.local` domains.
+- Configure local DNS to allow standard URLs to resolve locally across your entire network.
+- Manually map hosts files to ensure access on specific machines without internet.
+
+## Choose a connection method
+There are four ways to establish a local connection:
+
+* **[Method 1: Enable LarePass VPN](#method-1-enable-larepass-vpn)**<br/>
+  Uses LarePass VPN to automatically detect your local network and optimize the connection speed without changing settings.
+* **[Method 2: Use `.local` domain](#method-2-use-local-domain)**<br/>
+  Access the device via a specific local URL format. No installation required.
+* **[Method 3: Configure local DNS](#method-3-configure-local-dns)**<br/>
+  Updates your router or computer's DNS settings to map the standard Olares URL to the local IP address.
+* **[Method 4: Modify hosts files](#method-4-modify-hosts-files)**<br/>
+  Manually maps the standard Olares URL to the local IP on a single computer.
+
+## Method 1: Enable LarePass VPN
+The LarePass VPN is designed to secure your connection while optimizing performance. When enabled, LarePass detects if you are on the same network as your device and switches to **Intranet** mode.
+
+:::tip Always enable VPN for remote access
+Keep LarePass VPN enabled. It automatically prioritizes the fastest available route to ensure you always get the best speed possible without manual switching.
+:::
+:::info iOS and macOS setup
+On iOS or macOS, you may be prompted to add a VPN Configuration to your system settings the first time you enable the feature. Allow this to complete the setup.
+:::
+
+Enable the LarePass VPN directly on the device you are currently using to access Olares.
+
+<tabs>
+<template #On-LarePass-mobile-client>
+
+1. Open the LarePass app, and go to **Settings**.
+2. In the **My Olares** card, toggle on the VPN switch.
+
+   ![Enable LarePass VPN on mobile](/images/manual/get-started/larepass-vpn-mobile.png#bordered)
+</template>
+<template #On-LarePass-desktop-client>
+
+1. Open the LarePass app, and click your avatar in the top-left corner to open the user menu.
+2. Toggle on the switch for **VPN connection**.
+
+   ![Enable LarePass VPN on desktop](/images/manual/get-started/larepass-vpn-desktop.png#bordered)
+</template>
+</tabs>
+
+Once enabled, check the status indicator in LarePass to verify the connection type:
+
+| Status       | Description                                              |
+|:-------------|:---------------------------------------------------------|
+| **Intranet** | Direct connection via your local LAN IP. Fastest speeds. |
+| **P2P**      | Direct encrypted tunnel between devices. High speed.     |
+| **DERP**     | Routed via a secure relay server. Used as a fallback.    |
+
+## Method 2: Use `.local` domain
+If you prefer not to install additional apps, you can access services using the `.local` domain. There are two domain formats available depending on your operating system.
+
+:::info Use HTTP protocol
+The `.local` domain does not support HTTPS. You must explicitly use `http://` at the beginning of the URL.
+:::
+
+### Single-level domain (All operating systems)
+:::warning Supported for community apps only
+Olares system apps such as Desktop and Files do not support this URL format and will not load correctly.
+:::
+This format uses a single-level domain by connecting the entrance ID and the username with hyphens (`-`).
+- **Default URL**:
+   ```plain
+   https://<entrance_id>.<username>.olares.com
+   ```
+- **Local-access URL**:
+   ```plain
+   http://<entrance_id>-<username>-olares.local
+   ```
+
+### Multi-level domain (macOS and iOS only)
+Apple devices support local service discovery via [Bonjour](https://developer.apple.com/bonjour/) (zero‑configuration networking), which can resolve multi‑label domains under `.local` on macOS and iOS. This allows a local URL format that mirrors the remote address.
+
+- **Default URL**:
+   ```plain
+   https://<entrance_id>.<username>.olares.com
+   ```
+- **Local-access URL**:
+   ```plain
+   http://<entrance_id>.<username>.olares.local
+   ```
+![Multi-level local domain](/images/manual/get-started/multilevel-local-domain-mac.png#bordered)
+
+## Method 3: Configure local DNS
+For a seamless experience where standard URLs resolve to your local IP address automatically, you can configure your network DNS. This configuration ensures consistent access across all devices on the network without requiring individual client setup.
+
+### Find the internal IP for Olares device
+To configure DNS, first you need to find the internal IP for your Olares device.
+<tabs>
+<template #Check-via-the-LarePass-mobile-client>
+
+If your phone and Olares device are on the same network:
+1. Open the LarePass app, and go to **Settings** > **System** to navigate to the **Olares management** page
+   ![Tap the System card](/images/manual/get-started/larepass-system.png#bordered)
+
+2. Tap on the device card.
+   ![Tap the device card](/images/manual/get-started/larepass-device-card.png#bordered)
+
+3. Scroll down to the **Network** section. You can find the **Intranet IP** there.
+   ![Find Network section](/images/manual/get-started/larepass-network.png#bordered)
+
+</template>
+<template #Check-via-Olares-Terminal>
+
+Control Hub provides a built-in terminal that allows you to run system commands directly from the browser, without needing an external SSH client.
+1. Open the Control Hub app, and under **Terminal**, select **Olares** in the left navigation bar.
+   ![Find internal IP from Control Hub](/images/manual/get-started/find-internal-ip-from-controlhub.png#bordered)
+
+2. Type `ifconfig` in the terminal and press **Enter**.
+3. Look for your active connection, typically named `enp3s0` (wired) or `wlo1` (wireless). The IP address follows `inet`.
+
+   Example output:
+   ```bash
+    enp3s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
+    inet 192.168.50.116  netmask 255.255.255.0  broadcast 192.168.50.255
+    inet6 fe80::4194:4045:c35e:7b32  prefixlen 64  scopeid 0x20<link>
+    ether d8:43:ae:54:ce:fc  txqueuelen 1000  (Ethernet)
+    RX packets 80655321  bytes 71481515308 (71.4 GB)
+    RX errors 0  dropped 136  overruns 0  frame 0
+    TX packets 51867817  bytes 15924740708 (15.9 GB)
+    TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
+   ```
+   In this example, `192.168.50.116` is the internal IP.
+</template>
+</tabs>
+
+### Configure DNS
+With the internal IP address identified, you must now configure your DNS settings to route traffic correctly. You can apply this configuration to a single computer for individual access, or update your router to enable seamless local resolution for all devices on your network.
+<tabs>
+<template #Configure-for-local-device>
+
+Update the DNS settings on your specific computer. For example, on macOS:
+1. Open Apple menu and go to **System Settings**.
+2. Select **Wi-Fi**, then click **Details** on your connected network.
+3. Select **DNS** and update the server list:
+
+   a. Click the **+** button under **DNS Servers** to add your Olares device's internal IP (e.g., `192.168.x.x`).
+
+   b. Ensure the Olares IP is listed at the top. Add your original DNS (or `1.1.1.1`) below it as a fallback. <br/>This ensures that if your Olares device shuts down, the router will automatically switch to the secondary DNS, keeping your internet connection alive.
+
+4. Click **OK** to save changes.
+
+</template>
+
+<template #Configure-for-all-devices>
+
+Update the DNS on your router to apply changes to every device in your network.
+
+1.  Log in to your router's admin panel.
+2.  Navigate to **DHCP / DNS Settings**.
+3.  Set **Primary DNS** to your Olares device's internal IP (e.g., `192.168.x.x`).
+4.  Set **Secondary DNS** to your current Primary DNS (or a public provider like `1.1.1.1`). <br/>This ensures that if your Olares device shuts down, the router will automatically switch to the secondary DNS, keeping your internet connection alive.
+5.  Save and reconnect your devices to refresh the DNS cache.
+</template>
+</tabs>
+
+Once configured, you can access Olares using both your standard public address and your local address.
+:::tip
+You can install AdGuard Home from the Olares Market to monitor traffic and manage DNS mappings graphically.
+:::
+## Method 4: Modify hosts files
+If you cannot change router settings and need immediate offline access on a specific computer, you can manually map the domains in your hosts file.
+
+1. Locate your hosts file:
+   - **Windows**: `C:\Windows\System32\drivers\etc\hosts`
+   - **macOS/Linux**: `/etc/hosts`
+2. Open the file with a text editor, which requires Administrator privileges.
+3. Add the mapping lines:
+    ```plain
+    # Replace with the actual internal IP and the username
+    # Olares apps
+    192.168.31.208  desktop.<username>.olares.com
+    192.168.31.208  auth.<username>.olares.com
+    192.168.31.208  files.<username>.olares.com
+    192.168.31.208  market.<username>.olares.com
+    192.168.31.208  settings.<username>.olares.com
+    192.168.31.208  dashboard.<username>.olares.com
+    192.168.31.208  control-hub.<username>.olares.com
+    192.168.31.208  profile.<username>.olares.com
+    192.168.31.208  vault.<username>.olares.com
+    # Add other community apps as needed
+    192.168.31.208  <entrance_id>.<username>.olares.com
+    ```
+4. Save the file to apply changes and ensure local access without an internet connection.
+
+Verify the changes by checking the URL for quick loading or using the terminal:
+```bash
+ping desktop.<username>.olares.com
+```
+If the IP address starts with `192.168`, it indicates successful configuration.
+
+
+## FAQs
+### Why doesn't LarePass VPN work on my Mac anymore?
+If you successfully enabled the VPN previously, but it has stopped working, you might need to reset the system extension.
+:::info
+Depending on your macOS version, the UI might look slightly different.
+:::
+1. Open **System Settings**, search for "Extension", and select **Login Items & Extensions**.
+2. Scroll to the **Network Extensions** section and click the info icon (ⓘ) to view loaded extensions.
+3. Find LarePass, click the three dots (...), and select **Delete Extension**.
+4. Confirm the uninstallation.
+5. Restart your Mac and re-enable the VPN in the LarePass desktop client.
+
+### Why can't I enable LarePass VPN on Windows?
+Third-party antivirus software might mistakenly flag the LarePass desktop client as suspicious, preventing it from launching the VPN service.
+
+If prompted by your antivirus when opening LarePass for the first time, allow the application to continue.
+
+If the VPN still fails to enable:
+1. Open your security software and check if LarePass was blocked.
+2. Add the main LarePass executable to the allowlist or exclusions of your antivirus.
+3. Restart LarePass and enable the VPN.
+
+### Why the `.local` domain does not work in Chrome (macOS)?
+Chrome may fail to access local URLs if macOS blocks local network permissions.
+To enable access:
+1. Open Apple menu and go to **System Settings**.
+2. Go to **Privacy & Security** > **Local Network**.
+3. Find Google Chrome and Google Chrome Helper in the list and enable the toggles.
+   ![Enable local network](/images/manual/larepass/mac-chrome-local-access.png#bordered){width=400}
+
+4. Restart Chrome and try accessing the local URL again.
+
+### Why does the application fail to load in an iFrame when using a `.local` domain on Chrome (macOS)?
+Chrome might default to HTTPS when using local domains, and you might see a "connection not secure" warning.
+![Incorrect local address](/images/manual/get-started/incorrect-local-address.png#bordered)
+
+To address this, explicitly add the HTTP protocol (`http://`) to the beginning of the URL. This tells Chrome it's a local, non-encrypted connection, which is expected on your home network.

docs/manual/get-started/install-linux-docker.md

@@ -9,7 +9,33 @@ You can use Docker to install and run Olares in a containerized environment. Thi
 For best performance and stability, we recommend [installing Olares on Linux via script](/manual/get-started/install-olares.md).
 :::
 
-<!--@include: ./reusables.md{52,65}-->
+## System requirements
+
+Make sure your device meets the following requirements.
+
+### Required specifications
+
+- **CPU**: At least 4 cores.
+- **RAM**: At least 8 GB of available memory.
+- **Storage**: At least 150 GB of available SSD storage.
+  :::warning SSD required
+  The installation will fail if an HDD (mechanical hard drive) is used instead of an SSD.
+  :::
+- **Supported systems**:
+  - Ubuntu 22.04-25.04 LTS
+  - Debian 12 or 13
+
+:::info Version compatibility
+While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new).
+:::
+
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- **GPU (NVIDIA only)**:
+  - **Architecture**: Turing or newer (e.g., GTX 16 series, RTX 20 series).
+  - **Verification**: Run `lspci | grep -i nvidia` and check the [compatible GPU table](https://github.com/NVIDIA/open-gpu-kernel-modules?tab=readme-ov-file#compatible-gpus).
 
 ## Before you begin
 Before you begin, ensure the following:

docs/manual/get-started/install-linux-iso.md

@@ -1,4 +1,5 @@
 ---
+outline: [2, 3]
 description: Install Olares on a physical machine using the official ISO image, including system requirements, installation steps, and activation process.
 ---
 
@@ -10,6 +11,7 @@ This guide explains how to install Olares on a physical machine using the offici
 
 ## Prerequisites
 
+### Required
 - **Host requirements**:
   - **CPU**: Minimum 4 cores with **x86-64 architecture** (Intel or AMD). ARM-based processors are not currently supported for this method.
   - **Memory**: At least 8 GB of available RAM.
@@ -19,7 +21,15 @@ This guide explains how to install Olares on a physical machine using the offici
   The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
   :::
 
-- **Other**: A USB flash drive with at least **8 GB** capacity.
+- **USB flash drive**: **8 GB** capacity or larger.
+
+### Optional
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- **GPU (NVIDIA only)**:
+  - **Architecture**: Turing or newer (e.g., GTX 16 series, RTX 20 series).
+  - **Verification**: Run `lspci | grep -i nvidia` and check the [compatible GPU table](https://github.com/NVIDIA/open-gpu-kernel-modules?tab=readme-ov-file#compatible-gpus).
 
 ## Create a bootable USB drive
 

docs/manual/get-started/install-linux-script.md

@@ -1,4 +1,5 @@
 ---
+outline: [2, 3]
 description: Detailed instructions for installing Olares on Linux systems including Ubuntu and Debian. Covers system requirements, installation steps, and activation process.
 ---
 # Install Olares on Linux via the script
@@ -6,7 +7,33 @@ This guide explains how to install Olares on Linux using the provided installati
 
 <!--@include: ./reusables.md{44,51}-->
 
-<!--@include: ./reusables.md{52,65}-->
+## System requirements
+
+Make sure your device meets the following requirements.
+
+### Required specifications
+
+- **CPU**: At least 4 cores.
+- **RAM**: At least 8 GB of available memory.
+- **Storage**: At least 150 GB of available SSD storage.
+  :::warning SSD required
+  The installation will fail if an HDD (mechanical hard drive) is used instead of an SSD.
+  :::
+- **Supported systems**:
+  - Ubuntu 22.04-25.04 LTS
+  - Debian 12 or 13
+
+:::info Version compatibility
+While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new).
+:::
+
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- **GPU (NVIDIA only)**:
+  - **Architecture**: Turing or newer (e.g., GTX 16 series, RTX 20 series).
+  - **Verification**: Run `lspci | grep -i nvidia` and check the [compatible GPU table](https://github.com/NVIDIA/open-gpu-kernel-modules?tab=readme-ov-file#compatible-gpus).
 
 ## Install Olares
 

docs/manual/get-started/install-lxc.md

@@ -12,21 +12,31 @@ Currently, Olares on LXC has certain limitations. We recommend using it only for
 
 ## System requirements
 Make sure your device meets the following requirements.
-
+### Required specifications
 - CPU: At least 4 cores
-- RAM: At least 8GB of available memory
-- Storage: At least 150GB of available SSD storage.
+- RAM: At least 8 GB of available memory
+- Storage: At least 150 GB of available SSD storage.
+    ::: warning SSD required
+    The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+    :::
 - Supported systems:
     - PVE 8.2.2
     - Linux container: Debian 12 (for existing LXC containers on PVE)
-::: warning SSD required
-The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
-:::
+
 
 :::info Version compatibility
 While the specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new).
 :::
 
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- GPU (NVIDIA only):
+   - Architecture: Turing or newer (e.g., GTX 16 series, RTX 20 series, and later).
+   - Verification: Run `lspci | grep -i nvidia` in the PVE host shell to confirm the card is detected.
+   - Setup: To utilize the GPU, you must configure LXC device passthrough. Please refer to [Configure GPU passthrough in PVE](/manual/best-practices/install-olares-gpu-passthrough.md#configure-gpu-passthrough-in-pve) for detailed instructions.
+
 ## Prerequisites
 
 -  Working directories for storing images and packages on the PVE host. You can set it using the following command:

docs/manual/get-started/install-mac-docker.md

@@ -20,11 +20,14 @@ Make sure your device meets the following requirements.
 
 - Architecture: AMD64 or ARM64
 - CPU: At least 4 cores
-- RAM: At least 8GB of available memory
-- Storage: At least 150GB of available SSD storage. 
+- RAM: At least 8 GB of available memory
+- Storage: At least 150 GB of available SSD storage. 
 ::: warning SSD required
 The installation will fail if an HDD (mechanical hard drive) is used instead of an SSD.
 :::
+::: info GPU limitation
+Olares GPU acceleration currently supports NVIDIA GPUs only. Consequently, GPU resources cannot be managed or utilized for AI workloads on macOS devices.
+:::
 
 ## Before you begin
 Before you begin, ensure the following:

docs/manual/get-started/install-mac-script.md

@@ -16,12 +16,16 @@ We recommend using it only for development or testing purposes.
 
 ## System compatibility
 Make sure your Mac meets the following requirements.
-- Architecture: X86-64 or ARM64
-- RAM: 8 GB or above (available memory)
-- Storage: 150 GB or above of available space on SSD
-- MacOS: Monterey (12) or later
-::: warning SSD required
-The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+- Architecture: X86-64 or ARM64.
+- RAM: At least 8 GB of available memory.
+- Storage: At least 150 GB of available SSD storage.
+    ::: warning SSD required
+    The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+    :::
+- MacOS: Monterey (12) or later.
+
+::: info GPU limitation
+Olares GPU acceleration currently supports NVIDIA GPUs only. Consequently, GPU resources cannot be managed or utilized for AI workloads on macOS devices.
 :::
 
 ## Before you begin

docs/manual/get-started/install-pve-iso.md

@@ -12,12 +12,24 @@ Currently, Olares on PVE has certain limitations. We recommend using it only for
 
 ## System requirements
 Make sure your device meets the following requirements.
-
- **CPU**: Minimum 4 cores with **x86-64 architecture** (Intel or AMD). ARM-based processors are not currently supported for this method.
-- RAM: At least 8GB of available memory
-- Storage: At least 200GB of available SSD storage. The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+### Required specifications
+- CPU: Minimum 4 cores with x86-64 architecture (Intel or AMD). ARM-based processors are not currently supported for this method.
+- RAM: At least 8 GB of available memory
+- Storage: At least 200 GB of available SSD storage. 
+    ::: warning SSD required
+    The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+    :::
 - Supported Systems: PVE 8.2.2
 
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- GPU (NVIDIA only):
+   - Architecture: Turing or newer (e.g., GTX 16 series, RTX 20 series, and later).
+   - Verification: Run `lspci | grep -i nvidia` in the PVE host shell to confirm the card is detected.
+   - Setup: To utilize the GPU, you must configure PCI passthrough. Please refer to [Configure GPU passthrough in PVE](/manual/best-practices/install-olares-gpu-passthrough.md#configure-gpu-passthrough-in-pve) for detailed instructions.
+
 ## Download Olares ISO image
 Click [here](https://cdn.olares.com/olares-latest-amd64.iso) to download the official Olares ISO image.
 

docs/manual/get-started/install-pve-script.md

@@ -13,19 +13,28 @@ Currently, Olares on PVE has certain limitations. We recommend using it only for
 ## System requirements
 Make sure your device meets the following requirements.
 
+### Required specifications
 - CPU: At least 4 cores
-- RAM: At least 8GB of available memory
-- Storage: At least 150GB of available SSD storage. 
+- RAM: At least 8 GB of available memory
+- Storage: At least 150 GB of available SSD storage. 
+    ::: warning SSD required
+    The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+    :::
 - Supported Systems: PVE 8.2.2
 
-::: warning SSD required
-The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
-:::
-
 :::info Version compatibility
 While the specific version is confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new).
 :::
 
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- GPU (NVIDIA only):
+   - Architecture: Turing or newer (e.g., GTX 16 series, RTX 20 series, and later).
+   - Verification: Run `lspci | grep -i nvidia` in the PVE host shell to confirm the card is detected.
+   - Setup: To utilize the GPU, you must configure PCI passthrough. Please refer to [Configure GPU passthrough in PVE](/manual/best-practices/install-olares-gpu-passthrough.md#configure-gpu-passthrough-in-pve) for detailed instructions.
+
 ## Install on PVE
 
 In PVE CLI, run the following command:

docs/manual/get-started/install-raspberry-pi.md

@@ -14,10 +14,12 @@ Make sure your Raspbian device meets the following requirements.
 - Hardware: Raspberry Pi 4B or Raspberry Pi 5 with 8GB memory
 - Operating system: Raspbian 12
 - Storage: At least 150GB of available SSD storage. 
-
 ::: warning SSD required
 The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
 :::
+::: info GPU limitation
+Olares GPU acceleration currently supports NVIDIA GPUs only. Consequently, GPU resources cannot be managed or utilized for AI workloads on macOS devices.
+:::
 
 ## Set up system environment
 1. Configure the Raspbian environment to enable necessary features:

docs/manual/get-started/install-windows-script.md

@@ -17,15 +17,27 @@ We recommend using it only for development or testing purposes.
 
 ## System compatibility
 Make sure your Windows meets the following requirements.
+### Required specifications
 - CPU: At least 4 cores
-- RAM: At least 16GB of available memory
-- Storage: At least 150GB of available SSD storage. 
+- RAM: At least 16 GB of available memory
+- Storage: At least 150 GB of available SSD storage. 
+   ::: warning SSD required
+   The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
+   :::
 - Supported systems:
     - Windows 10 or 11
     - Linux (on WSL 2): Ubuntu 22.04 LTS or later; Debian 12 or later
-::: warning SSD required
-The installation will likely fail if an HDD (mechanical hard drive) is used instead of an SSD.
-:::
+
+### Optional hardware
+
+A GPU is not required to install Olares, but is necessary for AI applications.
+
+- **GPU (NVIDIA only)**:
+   - Architecture: Turing or newer (e.g., GTX 16 series, RTX 20 series, and later).
+   - Verification:
+      1. Open **Task Manager > Performance** to confirm your GPU model (must be NVIDIA).
+      2. Run `nvidia-smi` inside your WSL terminal to confirm the driver is accessible.
+
 ## Set up system environment
 1. Enable the required Windows features for virtualization.
 

docs/manual/get-started/local-access.md

@@ -1,24 +1,25 @@
 ---
 outline: [2,3]
-description: Learn how to access Olares apps and services directly via your local network (LAN) for maximum speed, privacy, and offline reliability.
+description: Learn how to access your Olares services securely using the LarePass VPN.
 ---
-# Access Olares services locally
+# Access Olares services securely using LarePass VPN
 
 Typically, you access Olares services through a browser using a URL like `https://desktop.<username>.olares.com`. This way, you can reach your services from any device at any time.
 
-However, accessing your devices directly over your Local Area Network (LAN) provides several advantages:
-- **Maximum performance**: Transfer files at full speed without the latency and potential bottlenecks of the internet.
-- **Enhanced privacy**: Keep your traffic contained within your home network for added security.
-- **Offline independence**: Access your data and apps even when your internet service is unavailable.
+While this address works from anywhere, it's recommended to enable the LarePass VPN to ensure your connection is always secure and efficient. The client automatically detects your network environment and selects the best connection method:
+- **At home**: It establishes a direct **Intranet** connection to allow faster file transfers on your local network.
+- **From remote**: It switches to a secure encrypted tunnel to ensure you remain connected safely when accessing remotely.
 
-This guide covers several methods to establish a local connection:
-- [Enable LarePass VPN (Recommended)](#method-1-enable-larepass-vpn)<br/>This method is the easiest solution, as it automatically establishes the fastest connection without manual configuration.
-- [Use `.local` domain](#method-2-use-local-domain)<br/>This method requires no installation, though you must use specific URL formats based on your operating system.
-- [Configure local DNS (Advanced)](#method-3-configure-local-dns)<br/>This method allows standard URLs to work locally by updating DNS settings on your router or individual computer.
-- [Modify host files (Fallback)](#method-4-modify-host-files)<br/>This method manually maps standard URLs to your local IP on a single computer, ensuring access even without an internet connection.
+## Download LarePass
+To use the secure VPN connection, the LarePass client must be installed on the device you are using.
+- **Mobile**: Use the LarePass app installed during the Olares ID creation process.
+- **Desktop**: Download and install the LarePass desktop client.
 
-## Method 1: Enable LarePass VPN
-The most robust way to connect, whether you are sitting next to the device or traveling, is using the LarePass VPN. It intelligently detects when you are on the same network and switches to a direct **Intranet** mode for maximum speed.
+1. Visit <AppLinkGlobal />.
+2. Download the version compatible with your operating system.
+
+## Enable LarePass VPN
+Once installed, enable the VPN directly on the device you are using to access Olares.
 
 :::tip Always enable VPN for remote access
 Keep LarePass VPN enabled. It automatically prioritizes the fastest available route to ensure you always get the best speed possible without manual switching.
@@ -27,25 +28,24 @@ Keep LarePass VPN enabled. It automatically prioritizes the fastest available ro
 On iOS or macOS, you may be prompted to add a VPN Configuration to your system settings the first time you enable the feature. Allow this to complete the setup.
 :::
 
-Enable the LarePass VPN directly on the device you are currently using to access Olares.
-
 <tabs>
 <template #On-LarePass-mobile-client>
 
-1. Open the LarePass app, and go to **Settings**.
+1. Open the LarePass app and go to **Settings**.
 2. In the **My Olares** card, toggle on the VPN switch.
 
    ![Enable LarePass VPN on mobile](/images/manual/get-started/larepass-vpn-mobile.png#bordered)
 </template>
 <template #On-LarePass-desktop-client>
 
-1. Open the LarePass app, and click your avatar in the top-left corner to open the user menu.
+1. Open the LarePass app and click your avatar in the top-left corner to open the user menu.
 2. Toggle on the switch for **VPN connection**.
 
    ![Enable LarePass VPN on desktop](/images/manual/get-started/larepass-vpn-desktop.png#bordered)
 </template>
 </tabs>
 
+## Verify the connection type
 Once enabled, check the status indicator in LarePass to verify the connection type:
 
 | Status       | Description                                              |
@@ -54,148 +54,6 @@ Once enabled, check the status indicator in LarePass to verify the connection ty
 | **P2P**      | Direct encrypted tunnel between devices. High speed.     |
 | **DERP**     | Routed via a secure relay server. Used as a fallback.    |
 
-## Method 2: Use `.local` domain
-If you prefer not to use a VPN, you can access services using the `.local` domain. There are two domain formats available depending on your compatibility needs.
-
-### Single-level domain (All operating systems)
-:::warning Supported for community apps only
-Olares system apps such as Desktop and Files do not support this URL format and will not load correctly.
-:::
-This format uses a single-level domain by connecting the entrance ID and the username with hyphens (`-`).
-- **Default URL**:
-   ```plain
-   https://<entrance_id>.<username>.olares.com
-   ```
-- **Local-access URL**:
-   ```plain
-   http://<entrance_id>-<username>-olares.local
-   ```
-
-### Multi-level domain (macOS and iOS only)
-Apple devices support local service discovery via [Bonjour](https://developer.apple.com/bonjour/) (zero‑configuration networking), which can resolve multi‑label domains under `.local` on macOS and iOS. This allows a local URL format that mirrors the remote address.
-
-- **Default URL**:
-   ```plain
-   https://<entrance_id>.<username>.olares.com
-   ```
-- **Local-access URL**:
-   ```plain
-   http://<entrance_id>.<username>.olares.local
-   ```
-![Multi-level local domain](/images/manual/get-started/multilevel-local-domain-mac.png#bordered)
-
-## Method 3: Configure local DNS
-For a seamless experience where standard URLs resolve to your local IP address automatically, you can configure your network DNS. This configuration ensures consistent access across all devices on the network without requiring individual client setup.
-
-### Find the internal IP for Olares device
-To configure DNS, first you need to find the internal IP for your Olares device.
-<tabs>
-<template #Check-via-the-LarePass-mobile-client>
-
-If your phone and Olares device are on the same network:
-1. Open the LarePass app, and go to **Settings** > **System** to navigate to the **Olares management** page
-   ![Tap the System card](/images/manual/get-started/larepass-system.png#bordered)
-
-2. Tap on the device card.
-   ![Tap the device card](/images/manual/get-started/larepass-device-card.png#bordered)
-
-3. Scroll down to the **Network** section. You can find the **Intranet IP** there.
-   ![Find Network section](/images/manual/get-started/larepass-network.png#bordered)
-
-</template>
-<template #Check-via-Olares-Terminal>
-
-Control Hub provides a built-in terminal that allows you to run system commands directly from the browser, without needing an external SSH client.
-1. Open the Control Hub app, and under **Terminal**, select **Olares**in the left navigation bar.
-   ![Find internal IP from Control Hub](/images/manual/get-started/find-internal-ip-from-controlhub.png#bordered)
-
-2. Type `ifconfig` in the terminal and press **Enter**.
-3. Look for your active connection, typically named `enp3s0` (wired) or `wlo1` (wireless). The IP address follows `inet`.
-
-   Example output:
-   ```bash
-    enp3s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
-    inet 192.168.50.116  netmask 255.255.255.0  broadcast 192.168.50.255
-    inet6 fe80::4194:4045:c35e:7b32  prefixlen 64  scopeid 0x20<link>
-    ether d8:43:ae:54:ce:fc  txqueuelen 1000  (Ethernet)
-    RX packets 80655321  bytes 71481515308 (71.4 GB)
-    RX errors 0  dropped 136  overruns 0  frame 0
-    TX packets 51867817  bytes 15924740708 (15.9 GB)
-    TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
-   ```
-   In this example, `192.168.50.116` is the internal IP.
-</template>
-</tabs>
-
-### Configure DNS
-With the internal IP address identified, you must now configure your DNS settings to route traffic correctly. You can apply this configuration to a single computer for individual access, or update your router to enable seamless local resolution for all devices on your network.
-<tabs>
-<template #Configure-for-local-device>
-
-Update the DNS settings on your specific computer. For example, on macOS:
-1. Open Apple menu and go to **System Settings**. 
-2. Select **Wi-Fi**, then click **Details** on your connected network.
-3. Select **DNS** and update the server list:
-
-   a. Click the **+** button under **DNS Servers** to add your Olares device's internal IP (e.g., `192.168.x.x`).
-
-   b. Ensure the Olares IP is listed at the top. Add your original DNS (or `1.1.1.1`) below it as a fallback. <br/>This ensures that if your Olares device shuts down, the router will automatically switch to the secondary DNS, keeping your internet connection alive.
-
-4. Click **OK** to save changes.
-
-</template>
-
-<template #Configure-for-all-devices>
-
-Update the DNS on your router to apply changes to every device in your network.
-
-1.  Log in to your router's admin panel.
-2.  Navigate to **DHCP / DNS Settings**.
-3.  Set **Primary DNS** to your Olares device's internal IP (e.g., `192.168.x.x`).
-4.  Set **Secondary DNS** to your current Primary DNS (or a public provider like `1.1.1.1`). <br/>This ensures that if your Olares device shuts down, the router will automatically switch to the secondary DNS, keeping your internet connection alive.
-5.  Save and reconnect your devices to refresh the DNS cache.
-</template>
-</tabs>
-
-Once configured, you can access Olares using both your standard public address and your local address.
-:::tip
-You can install AdGuard Home from the Olares Market to monitor traffic and manage DNS mappings graphically.
-:::
-## Method 4: Modify host files
-If you cannot change router settings and need immediate offline access on a specific computer, you can manually map the domains in your hosts file.
-
-1.  Locate your hosts file:
-    - **Windows:** `C:\Windows\System32\drivers\etc\hosts`
-    - **macOS/Linux:** `/etc/hosts`
-2.  Open the file with a text editor, which requires Administrator privileges.
-3.  Add the mapping lines:
-    ```plain
-    # Replace with the actual internal IP and the username
-    # Olares apps
-    192.168.31.208  desktop.<username>.olares.com
-    192.168.31.208  auth.<username>.olares.com
-    192.168.31.208  files.<username>.olares.com
-    192.168.31.208  market.<username>.olares.com
-    192.168.31.208  settings.<username>.olares.com
-    192.168.31.208  dashboard.<username>.olares.com
-    192.168.31.208  control-hub.<username>.olares.com
-    192.168.31.208  profile.<username>.olares.com
-    192.168.31.208  vault.<username>.olares.com
-    # Add other community apps as needed
-    192.168.31.208  <entrance_id>.<username>.olares.com
-    ```
-4. Save the file to apply changes and ensure local access without an internet connection.
-
-Verify the changes by checking the URL for quick loading or using the terminal:
-```bash
-ping desktop.<username>.olares.com
-```
-If the IP address starts with `192.168`, it indicates successful configuration.
-
-## Learn more
-- [Access Olares services remotely via LarePass VPN](../../manual/larepass/private-network.md): Understand how to use LarePass VPN.
-- [Network](../../developer/concepts/network.md): Learn about the different entry points in Olares.
-
 ## FAQs
 ### Why doesn't LarePass VPN work on my Mac anymore?
 If you successfully enabled the VPN previously, but it has stopped working, you might need to reset the system extension.
@@ -208,28 +66,16 @@ Depending on your macOS version, the UI might look slightly different.
 4. Confirm the uninstallation.
 5. Restart your Mac and re-enable the VPN in the LarePass desktop client.
 
-### Why I cannot enable LarePass VPN on Windows?
+### Why can't I enable LarePass VPN on Windows?
 Third-party antivirus software might mistakenly flag the LarePass desktop client as suspicious, preventing it from launching the VPN service.
 
 If prompted by your antivirus when opening LarePass for the first time, allow the application to continue.
 
 If the VPN still fails to enable:
 1. Open your security software and check if LarePass was blocked.
-2. Add the main LarePass executable to the allowlist** or exclusions of your antivirus. 
+2. Add the main LarePass executable to the allowlist or exclusions of your antivirus. 
 3. Restart LarePass and enable the VPN.
 
-### Why the `.local` domain does not work in Chrome (macOS)?
-Chrome may fail to access local URLs if macOS blocks local network permissions.
-To enable access:
-1. Open Apple menu and go to **System Settings**.
-2. Go to **Privacy & Security** > **Local Network**.
-3. Find Google Chrome and Google Chrome Helper in the list and enable the toggles.
-   ![Enable local network](/images/manual/larepass/mac-chrome-local-access.png#bordered){width=400}
-
-4. Restart Chrome and try accessing the local URL again.
-
-### Why does the application fail to load in an iFrame when using a `.local` domain on Chrome (macOS)?
-Chrome might default to HTTPS when using local domains, and you might see a "connection not secure" warning.
-![Incorrect local address](/images/manual/get-started/incorrect-local-address.png#bordered)
-
-To address this, explicitly add the HTTP protocol (`http://`) to the beginning of the URL. This tells Chrome it's a local, non-encrypted connection, which is expected on your home network.
+## Learn more
+- [Access Olares locally](../best-practices/local-access.md): Explore detailed instructions for all available local network connection methods.
+- [Network](../../developer/concepts/network.md): Learn about the different entry points in Olares.

docs/manual/get-started/reusables.md

@@ -62,4 +62,47 @@ Make sure your device meets the following requirements.
 
 :::info Version compatibility
 While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new).
-:::
+:::
+<!--Sync files, reused in LarePass > Manage files-->
+## Sync files to local computer
+
+With LarePass desktop, you can sync cloud files (organized by libraries or folders) to your local computer. This creates a corresponding folder on your machine. After set up, your files will stay updated bi-directionally in real time.
+
+:::tip Note
+The **Sync to local** feature is only available for libraries or folders within the **Sync** directory.
+:::
+
+### Create a library
+
+Library is the fundamental unit for organizing, syncing, and sharing your digital content. Each user is automatically provided with their own personal library (My Library) as a starting point. 
+
+To create a new library:
+
+1. To the right of **Sync**, click <i class="material-symbols-outlined">add_circle</i> to open the **New library** dialog.
+
+  ![Create a new library for sync](/images/manual/olares/sync-new-library.png#bordered){width=55%}
+
+2. Enter a name for the library and click **Create**.
+
+### Enable synchronization
+
+To enable sync for a library or folder: 
+
+1. Open LarePass desktop and locate the **Sync** directory.
+2. Hover your mouse over the target library or folder, click <i class="material-symbols-outlined">more_horiz</i>  that appears on the right, and then click **Sync to local**. 
+
+    ![Sync files to local](/images/manual/olares/sync-files-local.png#bordered){width=58%}
+    
+3. In the **Sync library** popup window, set the file download location, and then click **Confirm**. 
+    
+Syncing will begin immediately. Once completed, a green checkmark will appear on the bottom-left corner of the folder icon, indicating that the sync is finished.
+
+### Manage synchronization
+
+After setting up synchronization, you can manage your files and control the sync status with the following operations:
+
+- If you want to quickly locate the sync directory on your local drive, hover your mouse over the target library or folder, click <i class="material-symbols-outlined">more_horiz</i> that appears on the right, and then click **Open local sync folder**. The system will directly open the folder's location on your computer.
+
+- If you no longer need to sync a folder, hover your mouse over it, click <i class="material-symbols-outlined">more_horiz</i> that appears on the right, and then click **Unsychronize**.
+
+- If you want to temporarily stop data transfer, click <i class="material-symbols-outlined">pause_circle</i> to the right of the **Sync** directory. All sync tasks will be paused.

docs/manual/help/faqs.md

@@ -1,105 +1,2 @@
----
-description: Find answers to common questions about Olares.
----
 # FAQs
-
-## What license is Olares using?
-
-Olares consists of a series of projects using a hierarchical authorization approach. The basic principles are:
-
-- Projects running on blockchain use Apache 2.0, such as [Snowinning Protocol](https://github.com/beclab/terminusdid-contract-system).
-- Projects related to protocols use Apache 2.0, such as [r4](https://github.com/beclab/r4).
-- Projects around Olares and LarePass use the [Olares License](https://github.com/beclab/Olares/blob/main/LICENSE.md).
-- For third-party applications running on Olares, it is up to the developer to decide whether they want them open source or not and choose the license accordingly.
-
-For more details, visit our projects on [GitHub](https://github.com/beclab).
-
-## Is the Olares License an open source license?
-
-Olares's choice of license for its major projects is inspired by [fair code](https://faircode.io/). The [Olares License](https://github.com/beclab/Olares/blob/main/LICENSE.md) also follows these principles:
-
-> - Is generally free to use and can be distributed by anybody
-> - Has its source code openly available
-> - Can be extended by anybody in public and private communities
-> - Is commercially restricted by its authors
-
-## Why can't I restore my account if the mnemonics goes missing?
-
-From 1Password’s MasterKey to crypto wallet’s mnemonic phrase, for more than ten years, the problem of mnemonic storage has not been well solved.
-
-The mnemonic phrase of Olares will be encrypted and stored on all devices that install LarePass. Generally, you only lose the mnemonic phrase if you lose all the devices with LarePass installed at the same time.
-
-Safety is the most important principle in designing our system. We will continue to improve it in the future to provide you with a better solution that balances convenience and safety.
-
-## Is there a difference between Olares and the current operating systems running on NAS?
-
-At the inception of Olares (formerly Terminus), the market already had excellent NAS operating systems such as [Synology](https://www.synology.com/en-global/dsm/packages), [CasaOS](https://github.com/IceWhaleTech/CasaOS), and [Umbrel](https://github.com/getumbrel/umbrel). They have indeed inspired us.
-
-But we do think the operating system running on Edge should be able to:
-
-- Orchestrate resources for multiple hardware
-- Manage applications in sandboxes
-
-This is difficult to achieve with the above-mentioned NAS operating systems built on Docker Compose.
-
-Meanwhile, Olares aims to provide a one-stop self-hosted solution, which goes beyond the scope of general NAS operating systems.
-
-## Do I need to pay for Olares?
-
-When you're self-hosting, you can essentially use Olares for free.
-
-But for the following two features, we may introduce reasonable charges due to the cost (currently both are provided for free):
-
-- **Backup**
-
-  We provide 10G of free backup space for each Olares ID on Olares Space. When the archive size exceeds this limit, we will charge you a certain fee to cover the cloud provider fee.
-
-- **Fast Reverse Proxy (FRP)**
-
-   Accessing Olares locally or via VPN is essentially free. However, if you’re providing external services like hosting a blog, traffic will be forwarded to a Fast Reverse Proxy (FRP) server before reaching Olares. In this case:
-
-   - If you use your own FRP service, Olares does not impose any charges.
-   - If you opt to use the default FRP service from Olares, we offer a free monthly traffic allowance of 2GB. This is usually sufficient for users who do not provide external services through Olares. Additional charges may apply if your usage exceeds this limit.
-
-## When are other languages available?
-
-Right now we only support English and Simplified Chinese.
-
-In fact, we have completed i18n replacement in all front-end projects. However, we lack the experience in maintaining translation resources for a fast iterating project through the open source community. We are still learning.
-
-## What are the differences among the different "passwords"?
-
-Olares does have various passwords to ensure its security, including:
-
-- Private key
-- The password of LarePass:
-    - On mobile phones, biometrics can be used for login
-    - On computers and browser plug-ins, manual input is required
-- Password for first activation of Olares
-- Password for Olares login
-- Second verification code when logging in to Olares
-
-Don't panic! For daily use, what you need to enter is the two-step verification code when logging in to Olares.
-
-## How to deploy multi-user applications?
-
-It depends on whether you want to provide external service or simply let internal Olares users use it.
-
-- To provide services to the public, you can select the Entrance to access the application as **Public**. This allows the application to manage its own user registration and authentication.
-- To provide internal access only, you can deploy the Cluster-scoped version of such products on Olares.
-
-For Gitlab, we provide two versions of porting: [Gitlab Pure](https://github.com/beclab/apps/tree/main/gitlabpure) and [Gitlab Fusion](https://github.com/RLovelett/gitlab-fusion).
-
-## How can I reactivate Olares with the same Olares ID?
-
-If you've reinstalled Olares, the Olares instance you originally activated will no longer be accessible. To reactivate Olares using the same Olares ID:
-
-::: tip Install with the same Olares ID
-During the Olares installation, ensure that you have entered the exact same domain and Olares ID that you used previously. 
-:::
-
-![Reactivate](/images/manual/help/reactivate.png)
-
-  1. Open LarePass on your phone and enter your previous account. You should see a red prompt on the top saying "No active Olares found".
-  2. Tap **Learn more** > **Reactivate** to enter the QR scan screen.
-  3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares.
+This section summarizes frequently asked questions about Olares.

docs/manual/help/installation.md

@@ -0,0 +1,78 @@
+---
+outline: [2, 3]
+description: Find answers to common questions during the installation and activation of Olares.
+---
+# Olares installation and activation FAQs
+
+This page lists the FAQs about installing, configuring, and activating Olares on your hardware.
+
+## Installation
+### What platforms does Olares support?
+
+You can install Olares on Linux (Ubuntu or Debian) for best performance.
+
+For product evaluation, you can also install Olares on the following platforms:
+* Proxmox VE
+* Raspberry Pi
+* macOS
+* Windows
+
+### What is the minimum hardware requirements for installing Olares?
+
+The requirements vary by platform. Generally:
+* **CPU**: Minimum 4 cores with x86-64 architecture (Intel or AMD).
+* **Memory**: At least 8 GB of available RAM.
+* **Storage**: Minimum 150 GB SSD.
+
+For detailed requirements, refer to the [installation docs](../get-started/install-olares.md).
+
+### Can I use a mechanical hard drive to install Olares?
+
+No. You must use an SSD. The installation will likely fail if a mechanical hard drive is used due to slower read and write speeds, which can cause timeouts during the system initialization.
+
+### Does the system support NVIDIA GPUs?
+
+Yes. Olares is fully optimized for NVIDIA hardware. It automatically handles driver installation, allowing you to get immediate AI and gaming performance.
+
+It also supports multiple GPUs on a single motherboard (currently NVIDIA only), allowing users with custom hardware to leverage all available compute power for AI workloads.
+
+### How do I manually install NVIDIA drivers if the automatic setup fails?
+
+The Olares installer usually detects and installs drivers automatically. However, if your system previously had NVIDIA drivers installed, the process might be skipped or fail due to conflicts.
+
+In this case, you should:
+1. Reboot the machine after the Olares installation to ensure any old driver components are fully cleared.
+2. Manually trigger the driver installation using the command `olares-cli gpu install`.
+
+After installation, you can confirm that the drivers are installed and your GPU is recognized by running `nvidia-smi`.
+
+### Why does installation fail with `failed to build Kubernetes objects` or `Ensure CRDs are installed first`?
+
+While these error messages suggest a problem with Custom Resource Definitions (CRDs), they are often a symptom of poor disk performance.
+
+Olares relies on etcd, the backing database for Kubernetes. etcd is very sensitive to storage speed. If you are installing Olares on a slow disk, such as a traditional HDD, etcd cannot respond fast enough. This causes the API server to time out while attempting to apply CRDs.
+
+Installing Olares on SSD storage should fix this issue.
+
+### My Olares installation timed out and didn't show a password, but the system seems to be running. How can I find the password?
+This typically occurs when the installation times out due to insufficient system resources, especially in a virtual machine (VM). You can retrieve the password from the installation log file with the following command:
+```bash
+# Replace v1.12.2 with your specific Olares version number.
+grep password $HOME/.olares/versions/v1.12.2/logs/install.log
+```
+An installation timeout often means some services failed to start correctly. After finding your password, run  `kubectl get pod -A` to check the status of all services.
+
+## Activation
+### Is it possible to activate Olares with a non-local network?
+
+Yes. Before activation, users typically access the activation wizard using the local IP address, which generally requires both parties to be on the same network. However, if Olares is assigned a public IP, such as on a public cloud, this local network limitation no longer applies.
+
+Note that IP access is only used during activation. Once activated, devices can be accessed via domain names on both internal and external networks.
+
+### My Olares is powered on and connected to LAN, but I can't find it in LarePass. What should I do?
+
+Ensure both your phone and Olares device are on the same network. If they are not, LarePass cannot discover Olares automatically.
+
+In situations where you cannot connect via Wi-Fi, you can use the Bluetooth network setup in the LarePass app to connect Olares to the same network as your phone.
+
+For details, see [Activate Olares using Bluetooth](../../manual/larepass/activate-olares.md#activate-olares-using-bluetooth).

docs/manual/help/olares.md

@@ -0,0 +1,125 @@
+---
+outline: [2, 3]
+description: Find answers to common questions about the Olares platform.
+---
+
+# Olares FAQs
+
+This page lists most frequently asked questions about Olares.
+
+## General information
+
+### What is Olares?
+
+Olares is an open-source personal cloud operating system based on Kubernetes designed to empower users to own and manage their digital assets locally.
+
+It features native resource orchestration, application sandboxing, and production-grade infrastructure for edge computing. The goal of Olares is to provide a one-stop personal cloud solution that runs powerful local alternatives to public cloud services such as large language models and automation workflows. It is suitable for use cases ranging from personal media servers and AI development to decentralized identity management.
+
+### What is "personal cloud"?
+
+A personal cloud is a private infrastructure that replicates the utility of public cloud services such as anywhere-access to files and computing power but runs entirely on your own hardware to ensure data sovereignty.
+
+### Who is Olares for?
+
+Olares is designed for anyone who wants to use powerful AI tools locally without dealing with complex technical setups.
+
+* **For general users**: You can deploy complex applications like ComfyUI or Perplexica from the Market with a single click.
+* **For developers**: Olares functions as an efficient local development environment. You can leverage the sandboxing and agent infrastructure to build and test applications directly on your Olares device, saving time on environment configuration.
+
+### How is Olares different from NAS operating systems?
+
+Olares is designed fundamentally as a Personal AI Cloud rather than a storage server. Traditional NAS systems like Synology DSM or CasaOS are optimized primarily for storing files and hosting lightweight containers.
+
+Olares distinguishes itself by focusing on high-performance computing:
+* **Orchestrating resources**: It natively manages hardware resources such as GPUs to power local AI workloads.
+* **Sandboxing**: It enforces strict application isolation, providing a security model that goes beyond standard file servers.
+
+For detailed comparisons, refer to [Compare Olares and NAS](https://blog.olares.com/compare-olares-and-nas/).
+
+### Why is an Olares ID required?
+
+The Olares ID is currently required to automate secure remote access for your device. It allows the system to configure a reverse proxy, register a subdomain, and manage HTTPS certificates on your behalf. Without this, you would need to manually handle complex network configurations such as port forwarding and DNS management to access your device from outside your home.
+
+Unlike a centralized cloud account, the Olares ID is owned entirely by you. We never see your credentials, and we cannot recover your data if you lose your mnemonic phrase.
+
+We understand the community's preference for flexibility. In the upcoming March update, we plan to introduce new activation options that will make the Olares ID optional if you prefer to configure your own network access.
+
+### Can I use Olares offline or without internet?
+
+Yes, we support local-first usage, though the initial activation currently requires internet access.
+
+For users prioritizing strict local control, we offer these options:
+* **VPN-Only mode**: You can restrict your Olares so it is only accessible remotely via VPN.
+* **Local-Only access**: You can access Olares services via `.local` domains even if the router has no internet access.
+
+For detailed local access options, refer to [Access Olares services locally](../get-started/local-access.md).
+
+Note that we are also working on an option to allow full device activation in a completely offline environment.
+
+### What is LarePass and why is it required?
+
+LarePass is the official client for Olares. It acts as a secure bridge to enable seamless access, file synchronization across devices, etc. Currently, it is required to handle the device activation.
+
+### Can I use Olares without the LarePass app?
+
+We understand this is a core requirement for advanced users. We are working on decoupling these functions:
+
+* **CLI activation**: We plan to move activation logic into the `olares-cli`, allowing for a terminal-based setup without the app.
+* **Standalone components**: We aim to provide standalone deployment options for components like the Reverse Proxy, DID service, and Market repo in future updates.
+
+### Can I use my own domain name?
+
+Yes. You can use your own custom domain instead of the default `olares.com` domain. Note that setting this up currently requires the LarePass app.
+
+For details, refer to [Set up a custom domain for your Olares](../best-practices/set-custom-domain.md).
+
+### Do I need to pay for Olares?
+
+Olares OS itself is free and open source for self-hosting. If you purchase Olares One, it is a one-time hardware cost.
+
+We offer two optional cloud-assisted services for convenience, but free alternatives are available so you are never locked in:
+* **Cloud backup**: You can subscribe to Olares Space for integrated cloud backups. The free alternative is to back up to your own external storage or S3-compatible service.
+* **Remote access (FRP)**: For easy remote access, we offer a built-in FRP (Fast Reverse Proxy) service with 2 GB of free monthly traffic, with paid options for higher usage. The completely free alternative is to access Olares services via LarePass VPN, or to configure and use your own FRP server.
+
+### How often does Olares update?
+
+We aim for a major release approximately every 2 months. You can view specific changes in our [changelog](https://www.olares.com/changelog).
+
+## License
+### Is Olares open source?
+
+Yes. The Olares OS software is open source, ensuring transparency and community collaboration. The project consists of a family of repositories licensed under appropriate models:
+
+* **Olares and LarePass**: Licensed under AGPL-3.0. You can view our [GitHub organization](https://github.com/beclab).
+* **Protocol projects**: Projects like the Smart contract system for Olares ID use Apache 2.0.
+* **Third-party apps**: Developers adopt any license they choose.
+
+### Can I build Olares from source code?
+
+The short answer is yes, but it is currently complex.
+
+Olares is a massive project spanning over 90 repositories. Because our architecture is evolving quickly, we currently lack a fully integrated local build system that provides a simple "what you see is what you get" experience.
+
+We are actively working to streamline the build process and documentation. We expect to improve the local build experience and release standalone deployment guides for core services such as reverse proxy in 2026. Our goal is to refine the foundation first, then invite broader community collaboration.
+
+## Security and privacy
+
+### Does Olares collect my data?
+
+No. Olares is built to reclaim your data ownership. All storage, computation, and AI processing happen locally on your hardware. Olares does not collect or transmit your private data to any centralized service.
+
+### Does Olares support backup?
+
+Yes. Data safety is user-controlled and private. Olares includes a [built-in backup feature](../olares/settings/backup.md) that allows you to save specific file directories and set automatic schedules.
+
+Critically, every backup file is end-to-end encrypted. This allows you to store the backup file on any medium including external drive or third-party cloud with full confidence that the data remains inaccessible to others.
+
+### What is app sandboxing?
+
+Sandboxing is a security standard used to prevent a single malicious app from compromising the entire system. In Olares, every app runs in its own secure, isolated environment. If an app malfunctions, it is completely contained and cannot access or damage your other applications or personal data.
+
+### Does the system support multi-user environments?
+
+Yes. Olares supports sub-accounts with a built-in roles and permissions system including Super Admin, Admin, and Member.
+
+This allows a team to access shared tools on a single server. For example, you can share files within the same Olares cluster or install a large AI model once for everyone to use.