全栈服务器架构设计与目录规范 (Server Architecture Design)

目标：定义全栈服务器的软硬件架构标准，确保服务的高可用性、可移植性与长期可维护性。

---

1. 软件架构分层设计

系统采用 “宿主机基础层 + Docker 容器应用层” 的双层架构，实现业务与底层环境的解耦。

graph TD
    Hardware[Hardware: Server/VM] --> OS[OS: Linux / Ubuntu Server]
    OS --> Docker[Docker Engine]

    subgraph "Application Layer (Multi-Compose)"
        Proxy[Nginx Proxy / Gateway] --> Site[Static Sites]
        Proxy --> Hub[Integrated Services]
        Proxy --> App[Dynamic Apps / API]
        Monitor[Monitoring Stack] -.-> Proxy
    end

    Docker --> Proxy
    Docker --> Monitor

1.1 流量接入模型

• 统一入口：所有公网或局域网请求统一由接入层（Gateway）处理，负责 SSL 卸载与域名分发。
• 内网隔离：数据库、缓存等后端服务仅在 Docker 内部网络（Bridge Network）中通信，严禁将敏感端口映射到宿主机公网 IP。

---

2. 目录结构标准 (/srv 体系)

为了避免文件散乱并实现快速迁移，建议严格遵守 /srv 目录划分规范。

路径	用途	包含内容示例
/srv/core/	基础设施	网关 (Nginx)、穿透工具 (FRP)、容器管理 (Portainer)
/srv/app/	动态应用	后端 API 服务、数据库容器、私有业务逻辑
/srv/site/	静态站点	知识库 (VitePress)、个人主页、博客等静态资源
/srv/hub/	集成服务	网盘、媒体中心、相册等第三方开源服务
/srv/monitor/	监控审计	Prometheus, Grafana, 日志聚合工具
/srv/data/	持久化存储	大容量存储挂载点、应用数据卷、备份归档

运维原则：

1. 性能优先：所有 Docker 配置文件、代码及数据库文件应放在高速磁盘（如 SSD）上的 /srv/app 目录下。
2. 数据隔离：大容量非结构化数据（如上传的文件、媒体库）应存储在 /srv/data 下，通过 Docker Volume 挂载至对应容器。

---

3. 网络架构与端口规划

3.1 核心原则

1. 收口 80/443：宿主机仅对外暴露标准 Web 端口。
2. 容器互联：相关联的服务（如 API 与 DB）应处于同一 Docker 网络，使用容器名作为访问地址。
3. 禁用 Host 模式：除非必要（如 FRP 或某些监控工具），否则应使用 Bridge 模式以保证网络隔离。

3.2 典型服务清单

服务类型	内部端口 (Container)	宿主机端口 (Host)	说明
网关	80 / 443	80 / 443	唯一对外的流量入口
应用 API	5000 / 8080	-	不直接暴露，由网关反代
数据库	3306 / 5432	-	仅内网访问，生产严禁外挂端口
管理界面	9000 / 3000	9000 / 3000	建议仅限内网 IP 访问或加固认证

---

4. 环境隔离与配置管理

为了实现“一次构建，到处运行”并保护敏感数据，必须严格遵守配置隔离规范。

4.1 环境变量优先准则

• 禁止硬编码：数据库连接串、API 密钥、管理员密码严禁写在代码或 docker-compose.yml 中。

• .env 文件：每个项目目录下应维护一个 .env 文件，用于存放该环境特有的配置。

• 模板化：在源码仓库中提供 .env.example，仅包含键名，不包含真实值。

4.2 容器内部通信

• DNS 发现：在同一 Docker 网络下，服务间应通过 服务名 (Service Name) 访问，而非 IP。

• 隔离级别：

  • API 层：加入 proxy_net（与网关通信）和 app_internal（与 DB 通信）。
  • DB 层：仅加入 app_internal，彻底杜绝公网扫描风险。

---

5. 安全与备份策略

1. 最小权限：容器尽量以非 root 用户运行。
2. 配置隔离：敏感信息（密码、API Key）应通过 .env 文件或环境变量注入，严禁硬编码在代码或 docker-compose.yml 中。
3. 3-2-1 备份：重要配置与数据库定期备份，遵循“3 份副本、2 种介质、1 份异地”的原则。