fix

Author: spiritLHLS

docs/en/guide/oneclickvirt/images/portmapping-repair.png

@@ -63,6 +63,8 @@ For local nodes, only this section differs: choose `No Port Mapping`. You can th
 
 When manually adding port mapping, choose `Controller Forwarding (Intranet Penetration)`. Non-required fields can be left empty; the system will automatically select available controller ports for mapping.
 
+Controller forwarding uses a TCP tunnel and supports one TCP port per mapping. Create separate mappings when multiple ports must be exposed.
+
 ### Controller Deployment Requirements
 
 Because intranet penetration requires the controller to have control over the host machine's network and firewall, the controller must meet the following conditions:
@@ -178,4 +180,4 @@ After installation, running `nvidia-smi` inside the container should also return
 
 ![](./images/gpu3.jpg)
 
-At this point, you can stop this container and use it as a template. Use the redemption-code batch container creation "copy mode", set this container as the source container, and clone new containers from it.
+At this point, you can stop this container and use it as a template. Use the redemption-code batch container creation "copy mode", set this container as the source container, and clone new containers from it.

docs/en/guide/oneclickvirt/oneclickvirt_custom.md

@@ -498,6 +498,8 @@ docker run -d \
   oneclickvirt:no-db
 ```
 
+The `no-db` image stores its runtime configuration at `/app/storage/config.yaml` in the `oneclickvirt-storage` volume. Reuse the same storage volume when updating the image or recreating the container; database settings entered on the initialization page and other system-level settings then survive replacement, so database initialization is not repeated. Non-empty `DB_*` variables take precedence over the file, while deployments that explicitly mount `/app/config.yaml` continue to use that file first.
+
 ### One-Click Full-Stack Installation Script
 
 `install_full.sh` installs the database, reverse proxy, TLS configuration, frontend, backend, and system service in one flow. It supports MySQL or MariaDB and Caddy, Nginx, or OpenResty.

docs/en/guide/oneclickvirt/oneclickvirt_install.md

@@ -314,6 +314,16 @@ If you need images for any system, any virtualization environment, any architect
 
 Custom image addresses are temporarily not supported. The current frontend entry function is not available. Do not manually enter images.
 
+## Port Management
+
+Administrators can inspect and maintain port mapping records under **Resources > Port Management**. Node-side mappings are applied by the corresponding virtualization node. Controller forwarding is intended for tunnel access when a node has no public ingress and currently supports one TCP port per record.
+
+![](./images/portmapping-repair.png)
+
+**Sync Port Mappings** previews and removes stale database records, such as mappings whose instances no longer exist. **Rebuild Forwarding** repairs the opposite direction: selected controller database records are reapplied to the node or controller. The preview separates repairable, restart-required, and skipped records. Execution requires a risk confirmation followed by entering `REBUILD` exactly.
+
+Native container runtime bindings require restarting affected running instances, which causes a brief interruption. The task verifies the actual bindings after restart and reports a clear failure when they do not match the database. This operation does not delete controller database port mapping records.
+
 ## System Configuration
 
 General options here won't be elaborated on. There are two configurations that need special explanation.

docs/en/guide/oneclickvirt/oneclickvirt_usage.md

@@ -81,6 +81,8 @@ outline: deep
 
 对于非必填项，可以直接留空，系统会自动筛选并分配主控服务器可用端口。
 
+控制端转发使用 TCP 隧道，每条映射仅支持一个 TCP 端口。需要暴露多个端口时，请分别创建多条映射。
+
 ### 主控部署要求
 
 由于内网穿透功能需要主控具备对宿主机网络与防火墙的控制能力，因此主控必须满足以下条件

docs/guide/oneclickvirt/images/portmapping-repair.png

@@ -510,6 +510,8 @@ docker run -d \
   oneclickvirt:no-db
 ```
 
+`no-db` 镜像会将运行时配置保存到 `oneclickvirt-storage` 卷内的 `/app/storage/config.yaml`。更新镜像或重建容器时必须继续挂载同一个存储卷，初始化页面写入的数据库配置和系统级配置会随卷保留，无需重新初始化数据库。非空的 `DB_*` 环境变量优先于配置文件；显式挂载 `/app/config.yaml` 的部署仍优先使用该文件。
+
 ### 通过一键全栈安装脚本
 
 `install_full.sh` 可一键安装数据库、反向代理、TLS 配置、前端、后端及系统服务，支持 MySQL/MariaDB 以及 Caddy/Nginx/OpenResty。

docs/guide/oneclickvirt/oneclickvirt_custom.md

@@ -314,6 +314,16 @@ API是否可用不影响具体使用，自动配置API是非必需的
 
 暂时不支持自定义镜像地址，目前前端录入的功能是不可用的，不要手动录入镜像。
 
+## 端口管理
+
+管理员可在“资源 > 端口管理”中查看和维护控制端数据库记录的端口映射。手动添加映射时，节点侧映射由对应虚拟化节点写入转发规则；控制端转发适用于节点没有公网入口的内网穿透场景，目前每条记录只支持一个 TCP 端口。
+
+![](./images/portmapping-repair.png)
+
+“同步端口映射”用于预览并清理实例已不存在等情况下遗留的数据库记录。“重建转发规则”执行相反方向的修复：以控制端数据库为准，将选中的记录重新应用到节点或控制端。重建前会列出可修复、需重启和被跳过的记录；执行时需要先确认风险，再完整输入 `REBUILD` 进行二次确认。
+
+容器运行时的原生端口绑定需要重启对应的运行中实例，期间会有短暂中断。任务会在重启后核验实际绑定，未按数据库记录生效时会明确标记失败。该操作不会删除控制端数据库中的端口映射记录。
+
 ## 系统配置
 
 一般的选项这里不多赘述了，有必要特殊说明的就两个配置。