修改 wiki

.qoder/repowiki/zh/content/部署与运维/部署指南.md

@@ -20,6 +20,13 @@
 - [frontend/vite.config.js](file://frontend/vite.config.js)
 </cite>
 
+## 更新摘要
+**变更内容**
+- 更新了Docker Compose配置说明，突出网络和卷挂载优化
+- 增强了前后端服务连接稳定性的配置细节
+- 添加了网络隔离和容器间通信的配置说明
+- 完善了卷挂载的安全性和性能考虑
+
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
@@ -41,10 +48,11 @@
 - 后端容器暴露 8000 端口，并通过环境变量 PORT 固定该值以匹配 Nginx 代理。
 - 日志采用 JSON 文件轮转策略，单文件最大 10MB，最多保留 5 份。
 - 提供 OTA 升级包本地存储卷挂载，便于 X9 设备升级包管理。
+- **新增**：使用自定义桥接网络 `audio-network` 确保容器间通信的稳定性和安全性。
 
 ```mermaid
 graph TB
-subgraph "服务器"
+subgraph "Docker 网络 audio-network"
 FE["Nginx 前端<br/>端口 80 映射 8082"]
 BE["Node.js 后端<br/>端口 8000 映射 8083"]
 VOL1["/data/project/dashboard/frontend/dist"]
@@ -55,12 +63,12 @@ FE --- VOL1
 BE --- VOL2
 ```
 
-图表来源
+**图表来源**
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 - [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
 
-章节来源
-- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
+**章节来源**
+- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
 - [DEPLOY.md:1-16](file://DEPLOY.md#L1-L16)
 
 ## 核心组件
@@ -68,10 +76,12 @@ BE --- VOL2
   - 基于 Node.js 22 Alpine，使用 pnpm 作为包管理器，生产依赖安装在容器内完成。
   - 通过环境变量 PORT=8000 固定容器内端口，与 Nginx 代理保持一致。
   - 日志目录在容器内创建，便于持久化与查看。
+  - **新增**：加入 `extra_hosts` 配置支持 `host.docker.internal` 访问宿主机。
 - 前端服务（Nginx）
   - 使用 nginx:alpine 镜像，直接挂载服务器上的 dist 与 nginx.conf。
   - Nginx 监听 80 端口，将 /api 请求代理到后端容器的 8000 端口。
   - 支持静态资源缓存与上传大小限制。
+  - **新增**：卷挂载使用只读模式 (`:ro`) 提升安全性。
 - 上传脚本（upload.sh）
   - 基于 rsync + SSH，支持分模块上传（frontend、backend、compose），也支持自定义路径。
   - 提供虚拟执行（-n）预览能力，便于确认同步范围。
@@ -80,12 +90,12 @@ BE --- VOL2
   - 后端支持通过 APP_ENV 切换开发/生产环境行为。
   - JWT 密钥、管理员密码等敏感信息需在生产环境强制替换。
 
-章节来源
+**章节来源**
 - [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
 - [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
 - [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
 - [frontend/nginx.conf:1-34](file://frontend/nginx.conf#L1-L34)
-- [backend/src/config/env.js:1-12](file://backend/src/config/env.js#L1-L12)
+- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
 - [backend/src/config/loadEnv.js:1-14](file://backend/src/config/loadEnv.js#L1-L14)
 - [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)
 
@@ -94,21 +104,26 @@ BE --- VOL2
 - 前端静态资源来自服务器上的 dist 目录，Nginx 直接挂载。
 - 后端容器挂载 OTA 升级包存储目录，便于设备侧访问。
 - Docker Compose 控制服务生命周期与网络隔离。
+- **新增**：所有服务加入自定义桥接网络 `audio-network`，确保容器间通信的稳定性和安全性。
 
 ```mermaid
 graph TB
 U["用户浏览器"] --> P["宿主机端口 8082/Nginx"]
 P --> |"/api 代理"| B["后端容器 8000"]
-P --> |静态资源"| D["/data/project/dashboard/frontend/dist"]
+P --> |静态资源| D["/data/project/dashboard/frontend/dist"]
 B --> S["OTA 存储卷 /data/projects/source"]
+subgraph "Docker 网络 audio-network"
+B
+P
+end
 ```
 
-图表来源
+**图表来源**
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 - [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
 
-章节来源
-- [DEPLOY.md:5-16](file://DEPLY.md#L5-L16)
+**章节来源**
+- [DEPLOY.md:5-16](file://DEPLOY.md#L5-L16)
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 
 ## 详细组件分析
@@ -122,9 +137,9 @@ B --> S["OTA 存储卷 /data/projects/source"]
   - 关键点：PORT=8000（容器内固定）、JWT_SECRET、DASHBOARD_ADMIN_PASSWORD、数据库、搜索、S3、Redis、OTA 等参数
   - .env 不会被上传脚本自动上传，需在服务器单独维护
 - 上传代码并启动
-  - 参考“本地构建 + 上传”章节
+  - 参考"本地构建 + 上传"章节
 
-章节来源
+**章节来源**
 - [DEPLOY.md:18-46](file://DEPLOY.md#L18-L46)
 
 ### 本地构建 + 上传（推荐）
@@ -146,7 +161,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
     - 后端 API：http://服务器 IP:8083/api/...
     - 健康检查：http://服务器 IP:8083/health
 
-章节来源
+**章节来源**
 - [DEPLOY.md:49-120](file://DEPLOY.md#L49-L120)
 - [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
 - [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
@@ -159,7 +174,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - 一键流程
   - 本地构建前端并上传，服务器执行后端镜像构建与启动
 
-章节来源
+**章节来源**
 - [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
 
 ### docker-compose.yml 说明
@@ -168,17 +183,21 @@ B --> S["OTA 存储卷 /data/projects/source"]
   - environment: 设置 PORT=8000，覆盖容器内端口
   - ports: 8083:8000（宿主:容器）
   - volumes: 挂载 OTA 存储目录
+  - **新增**：networks: audio-network 加入自定义网络
+  - **新增**：extra_hosts: host.docker.internal:host-gateway 支持宿主机访问
 - frontend
   - image: nginx:alpine
   - ports: 8082:80
-  - volumes: 挂载 dist 与 nginx.conf
+  - volumes: 挂载 dist 与 nginx.conf（只读模式 :ro）
   - depends_on: 依赖后端容器
+  - **新增**：networks: audio-network 加入自定义网络
 - 日志轮转
   - 每个服务启用 json-file，单文件最大 10MB，最多 5 份
 - 网络
-  - 使用自定义桥接网络 audio-network，便于容器间通信
+  - **新增**：使用自定义桥接网络 audio-network，便于容器间通信
+  - **新增**：网络驱动为 bridge，提供容器间隔离和通信
 
-章节来源
+**章节来源**
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 - [DEPLOY.md:157-171](file://DEPLOY.md#L157-L171)
 
@@ -186,7 +205,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - 后端镜像构建所需文件
   - Dockerfile、package.json、pnpm-lock.yaml、src/
 
-章节来源
+**章节来源**
 - [DEPLOY.md:174-187](file://DEPLOY.md#L174-L187)
 
 ### 环境变量参考
@@ -198,7 +217,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - OTA：OTA_X8_PUBLIC_BASE、OTA_X9_URL_BASE、OTA_UPLOAD_DIR
 - Redis EQ：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_EQ_DB
 
-章节来源
+**章节来源**
 - [DEPLOY.md:190-203](file://DEPLOY.md#L190-L203)
 
 ### 目录结构（服务器）
@@ -215,7 +234,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
     - nginx.conf
 - /data/projects/source/（OTA 升级包存储）
 
-章节来源
+**章节来源**
 - [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)
 
 ### 上传脚本使用方法
@@ -229,7 +248,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
   - 默认不同步 nginx.conf 与 Dockerfile，需要时需显式指定
   - 路径不在项目内会被跳过
 
-章节来源
+**章节来源**
 - [scripts/upload.sh:39-75](file://scripts/upload.sh#L39-L75)
 - [scripts/upload.sh:142-187](file://scripts/upload.sh#L142-L187)
 
@@ -243,7 +262,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - Compose
   - scp docker-compose.yml 至服务器根目录
 
-章节来源
+**章节来源**
 - [DEPLOY.md:77-91](file://DEPLOY.md#L77-L91)
 
 ### 构建与启动命令
@@ -255,7 +274,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - 停止服务
   - docker compose down
 
-章节来源
+**章节来源**
 - [DEPLOY.md:92-103](file://DEPLOY.md#L92-L103)
 - [DEPLOY.md:251-256](file://DEPLOY.md#L251-L256)
 
@@ -269,7 +288,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
   - 前端：http://服务器 IP:8082
   - 后端 API：http://服务器 IP:8083/api/...
 
-章节来源
+**章节来源**
 - [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)
 
 ### 后端本地脚本（非 Docker）
@@ -277,7 +296,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - restart.sh：停止占用 8083 端口的进程并重启服务
 - stop.sh：查找并终止占用 8083 端口的进程
 
-章节来源
+**章节来源**
 - [backend/start.sh:1-5](file://backend/start.sh#L1-L5)
 - [backend/restart.sh:1-43](file://backend/restart.sh#L1-L43)
 - [backend/stop.sh:1-14](file://backend/stop.sh#L1-L14)
@@ -289,7 +308,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
   - 监听 80，将 /api 代理到后端容器 8000
   - 支持静态资源缓存与上传大小限制
 
-章节来源
+**章节来源**
 - [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
 - [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
 
@@ -303,6 +322,7 @@ B --> S["OTA 存储卷 /data/projects/source"]
 - 外部依赖与集成点
   - Docker Compose 管理服务生命周期与网络
   - Nginx 作为反向代理与静态资源服务
+  - **新增**：自定义网络 audio-network 提供容器间通信
 
 ```mermaid
 graph LR
@@ -312,13 +332,17 @@ BE --> DB["数据库"]
 BE --> MEILI["Meilisearch"]
 BE --> S3["S3 对象存储"]
 BE --> REDIS["Redis"]
+subgraph "Docker 网络 audio-network"
+NGINX
+BE
+end
 ```
 
-图表来源
+**图表来源**
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 - [frontend/nginx.conf:11-21](file://frontend/nginx.conf#L11-L21)
 
-章节来源
+**章节来源**
 - [backend/package.json:1-29](file://backend/package.json#L1-L29)
 - [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
 
@@ -329,10 +353,16 @@ BE --> REDIS["Redis"]
   - Nginx 对静态资源进行缓存与压缩，提升前端加载速度
 - 端口与网络
   - 明确的端口映射与自定义桥接网络，减少冲突与提升隔离性
+- **新增**：卷挂载优化
+  - 前端卷挂载使用只读模式 (:ro)，提升安全性和性能
+  - 后端 OTA 存储卷直接映射宿主机目录，避免额外开销
+- **新增**：网络优化
+  - 自定义桥接网络减少网络延迟
+  - 容器间通信通过内部网络，不经过宿主机网络栈
 
-章节来源
+**章节来源**
 - [docker-compose.yml:1-5](file://docker-compose.yml#L1-L5)
-- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-L32)
+- [frontend/nginx.conf:7-32](file://frontend/nginx.conf#L7-32)
 
 ## 故障排查指南
 - 前端页面空白
@@ -343,19 +373,26 @@ BE --> REDIS["Redis"]
   - 确认后端容器处于 running 状态
   - 查看后端日志，定位数据库、Redis、Meilisearch 连接问题
   - 确认 Nginx 代理目标为 http://backend:8000
+  - **新增**：检查容器是否在同一个网络中：`docker network inspect audio-network`
 - 后端构建失败（pnpm / Node 版本）
   - 后端镜像基于 node:22-alpine，确保上传了 package.json 与 pnpm-lock.yaml
 - 修改 .env 后不生效
   - 通过 docker compose up -d --force-recreate 使新环境变量生效
+- 网络相关问题
+  - **新增**：检查网络连通性：`docker exec dashboard-frontend ping backend`
+  - **新增**：查看网络配置：`docker network ls`
+  - **新增**：检查容器网络：`docker inspect dashboard-backend | grep NetworkMode`
 - 停止服务
   - docker compose down
 
-章节来源
+**章节来源**
 - [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
 
 ## 结论
 本指南提供了从服务器准备、目录与环境配置、本地构建与上传、Docker Compose 编排与启动、健康检查与验证，到更新部署与故障排查的完整流程。遵循本文档可快速、稳定地完成 Audio Dashboard 的部署与运维。
 
+**新增**：通过自定义网络、只读卷挂载和额外的主机配置，系统在网络稳定性和安全性方面得到了显著提升。
+
 ## 附录
 
 ### 环境变量与安全配置建议
@@ -366,12 +403,16 @@ BE --> REDIS["Redis"]
   - S3 通常通过云服务 IAM 角色访问，避免在 .env 中硬编码密钥
 - 网络与端口
   - 仅开放必要端口，防火墙策略最小化
+  - **新增**：利用 Docker 网络隔离，避免不必要的端口暴露
 - 日志与监控
   - 结合日志轮转与容器日志采集，定期巡检
 - 配置加载
   - 后端通过 APP_ENV 切换开发/生产行为，确保生产环境严格校验
+- **新增**：卷挂载安全
+  - 前端静态资源使用只读挂载 (:ro)，防止运行时修改
+  - 后端数据卷根据业务需求选择合适的挂载模式
 
-章节来源
+**章节来源**
 - [DEPLOY.md:36-42](file://DEPLOY.md#L36-L42)
-- [backend/src/config/env.js:1-12](file://backend/src/config/env.js#L1-L12)
+- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
 - [backend/src/utils/jwt.js:1-27](file://backend/src/utils/jwt.js#L1-L27)