当前位置：首页 > news >正文

CentOS 7 部署 Eclipse Theia 云 IDE 实战：Docker Compose + nginx-proxy 生产方案

news 2026/6/22 3:45:46

1. 项目概述：为什么要在 CentOS 7 上部署 Eclipse Theia？这真不是“为了用而用”

Eclipse Theia 是一个真正意义上的现代化云 IDE 平台，它不是 VS Code 的简单克隆，也不是某个厂商闭源产品的 Web 包装版。它基于 TypeScript 构建，采用模块化微前端架构，核心组件（编辑器、调试器、终端、文件系统抽象层）全部可插拔、可替换、可独立升级。我在实际带三个远程开发团队做嵌入式固件、Kubernetes 运维工具链和 Python 数据分析平台时，发现传统本地 IDE 在协作效率、环境一致性、权限管控和资源复用上存在硬伤——比如新同事花两天配好本地 VS Code + PlatformIO + Jupyter 插件，结果发现 Python 环境版本和团队 CI 服务器不一致；又比如测试工程师需要临时调试一个 Java 微服务，但他的笔记本跑不动全套 IntelliJ IDEA，只能靠截图+文字描述来回沟通。Eclipse Theia 就是为解决这类问题而生的：它把整个开发环境“收编”到服务器端，用户通过浏览器访问，所有计算、编译、调试都在后端完成，前端只负责渲染和交互。关键词Eclipse Theia、CentOS 7、cloud IDE、Docker Compose、nginx-proxy全部指向一个明确目标：在企业级稳定操作系统上，用容器化方式，构建一个生产就绪、可多租户隔离、能无缝集成现有认证体系的云端开发平台。

为什么选CentOS 7而不是 Ubuntu 或 Rocky Linux？这不是怀旧，而是现实约束。我接手的客户环境里，83% 的生产中间件服务器（Oracle WebLogic、IBM MQ、SAP NetWeaver）仍运行在 CentOS 7.9 x86_64 上，内核版本 3.10.0-1160，glibc 2.17。这意味着任何依赖较新内核特性（如 cgroup v2）或新版 glibc 的容器镜像，在部署时都会报错退出。Theia 官方推荐的 Node.js 版本是 18.x，但 CentOS 7 默认仓库只提供 Node.js 10.x，强行升级会破坏系统 Python 2.7 的依赖关系（很多运维脚本还依赖它）。所以必须用 Docker 隔离运行时环境——这正是Docker Compose成为不可替代工具的原因：它能精确声明 Theia 服务、反向代理、SSL 终止、静态资源缓存等组件的启动顺序、网络拓扑和卷挂载策略，避免手动敲一堆docker run命令导致的配置漂移。而nginx-proxy不是随便选的，它是社区验证最成熟的自动反向代理方案，配合docker-gen可以实现“容器一启动，域名自动生效”，省去每次手动改 Nginx 配置、reload 服务的繁琐操作，这对需要快速交付多个项目环境的 DevOps 团队来说，节省的是实打实的人力成本。你可能在网上搜到“vmware虚拟机安装centos 7”或“centos 7 minimal 下载”，这些关键词背后的真实需求是：如何在一台物理服务器上，用最小化安装的 CentOS 7，构建一个安全、稳定、可审计的云 IDE 底座。这恰恰是我们要解决的核心问题——不是教你怎么装系统，而是告诉你装完之后，每一步配置背后的业务逻辑和安全考量。

2. 整体架构设计与技术选型依据：为什么不用 Kubernetes？为什么坚持用 nginx-proxy？

2.1 架构全景图：四层解耦，各司其职

整个平台不是把 Theia 打包成一个大镜像扔进容器就完事了。我把它拆成四个清晰的逻辑层，每一层都解决一类特定问题：

基础设施层（Infrastructure Layer）：CentOS 7 主机 + Docker Engine 20.10.24 + Docker Compose v2.20.2。这里的关键是 Docker 版本选择。CentOS 7.9 的内核 3.10.0 对较新 Docker 存在兼容性问题，官方明确要求 Docker Engine 20.10.x 是最后一个支持该内核的稳定系列。我试过直接装 Docker 24.x，结果dockerd启动失败，日志里反复出现cgroup: cgroup2: unknown option "nsdelegate"错误——这是内核不支持 cgroup v2 的典型表现。所以必须锁定 20.10.x，并禁用 cgroup v2：在/etc/docker/daemon.json中添加"exec-opts": ["native.cgroupdriver=systemd"]和"features": {"buildkit": true}，然后systemctl restart docker。这个细节网上很多教程都忽略，导致后续 Compose 启动失败却找不到原因。
网络与接入层（Network & Ingress Layer）：nginx-proxy+letsencrypt-nginx-proxy-companion。很多人问为什么不直接用 Nginx 手动配置？因为手动配置无法应对动态扩缩容。假设你今天部署了 theia-proj-a，明天要加 theia-proj-b，手动改 Nginx 配置、生成证书、reload 服务，每次都要人工介入，出错概率高。nginx-proxy的核心价值在于它的自动化机制：它监听 Docker daemon 的事件流，一旦检测到新容器启动且带有VIRTUAL_HOST=theia-proj-a.example.com标签，就自动更新 Nginx 配置并 reload。letsencrypt-nginx-proxy-companion则负责自动申请和续期 Let's Encrypt 证书。我实测过，从docker-compose up -d到浏览器打开https://theia-proj-a.example.com显示绿色锁图标，全程不到 90 秒，且证书有效期自动续期，无需人工干预。这就是为什么它比单纯用traefik或haproxy更适合中小团队——复杂度低，稳定性高，文档成熟。
应用服务层（Application Service Layer）：Eclipse Theia 容器本身。这里有个关键决策：用官方镜像还是自建？官方eclipse/theia-full:latest镜像体积超过 2GB，包含大量开发语言支持（Go、Rust、Java），但我们的团队只用 Python 和 JavaScript。盲目使用会导致镜像拉取慢、磁盘占用高、安全扫描漏洞多（因为包含了不必要的二进制文件）。所以我选择基于eclipse/theia-python:latest基础镜像，通过Dockerfile精简定制：删除apt-get install阶段安装的gcc、g++、make等编译工具（开发环境在容器内，编译在宿主机或 CI 流水线完成），只保留python3-pip、nodejs、npm和git。最终镜像大小压到 850MB，启动时间从 42 秒缩短到 18 秒，Clair 扫描漏洞数从 137 个降到 21 个。这个精简过程不是简单的apt-get remove，而是要逐行分析theia-python的 Dockerfile，理解每个RUN指令的用途，再决定是否保留。
数据与安全层（Data & Security Layer）：volumes挂载策略 + 密码策略强制实施。volumes不是随便写个- ./workspace:/home/project就完事。Theia 的工作区（workspace）必须挂载到容器内非 root 用户的家目录下，否则会出现权限拒绝错误（Permission denied when saving file）。我定义了两个关键卷：theia-workspace用于持久化用户代码，theia-config用于保存用户个性化设置（主题、快捷键、插件列表）。更重要的是，theia-workspace必须设置为:z或:ZSELinux 标签（CentOS 7 默认启用 SELinux），否则容器内进程无法读写挂载目录。这个细节在 Ubuntu 上不存在，但在 CentOS 7 上是必填项，漏掉就会卡在登录后空白页。至于密码策略，centos 7 minimal安装后默认不启用 PAM 密码强度检查。我们必须手动配置/etc/pam.d/system-auth，加入password requisite pam_pwquality.so try_first_pass local_users_only retry=3 authtok_type= minlen=8 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=-1 maxrepeat=2这一行，才能满足“最小密码长度为8位，最小字符类型数为4种（大小写字母、数字、特殊符号），同一类最大连续字符数为2”的硬性要求。这不是可选项，而是等保 2.0 和 ISO 27001 审计的明确条款。

2.2 为什么放弃 Kubernetes？一个被低估的现实成本

看到这里，你可能会想：既然都用 Docker 了，为什么不直接上 Kubernetes？毕竟 K8s 是云原生标配。我必须坦诚地说：在 CentOS 7 环境下，K8s 不是银弹，而是负担。我们做过详细对比测试：在一台 32GB 内存、8 核 CPU 的 Dell R740 服务器上，部署一套最小化的 K8s 集群（kubeadm + containerd + Calico CNI），仅控制平面（etcd、kube-apiserver、scheduler、controller-manager）就常驻消耗 4.2GB 内存和 1.8 个 CPU 核心。而我们的 Theia 平台，单实例峰值内存占用 1.2GB，CPU 占用 0.7 核。这意味着，如果上 K8s，光是“养”集群的成本就占了总资源的 65%。更麻烦的是兼容性：Kubernetes 1.24+ 已完全弃用 Docker Shim，要求使用 containerd 或 CRI-O。但 CentOS 7 的containerd包在 EPEL 仓库中版本太老（1.4.x），不支持 K8s 1.24 的 CRI 接口，强行升级又会破坏 Docker Engine 的稳定性。我们曾尝试用k3s（轻量版 K8s），但它在 CentOS 7 上的 systemd 服务管理存在 bug，k3s-server进程偶尔会因fork()失败而崩溃，日志里全是Cannot allocate memory，根源是 CentOS 7 的vm.max_map_count默认值（65530）远低于 k3s 推荐值（262144），而修改这个参数需要重启服务器，这在生产环境是不可接受的。相比之下，Docker Compose 的资源开销几乎为零，所有组件都作为普通进程运行，故障排查路径清晰（docker logs、docker exec -it直接进容器），学习曲线平缓。对于一个 5-20 人规模的开发团队，Docker Compose 提供的可靠性、可维护性和成本效益，远超 K8s 带来的所谓“先进性”。

2.3 nginx-proxy 的替代方案评估：traefik vs haproxy vs 手动 nginx

nginx-proxy是当前方案的核心，但它的地位并非不可撼动。我们曾深度评估过三种主流替代方案：

Traefik：优势是动态配置、内置 Let's Encrypt、Dashboard 可视化。但问题在于它的acme.json证书存储机制。Traefik 要求acme.json文件权限必须是600，且只能由 Traefik 进程自己读写。在 Docker Compose 环境下，如果多个 Traefik 实例（比如为不同环境部署）共享同一个acme.json，会因文件锁竞争导致证书申请失败。我们测试时发现，当并发启动 3 个 Traefik 实例时，有 40% 的概率出现failed to obtain certificate: acme: error: 429 :: POST :: https://acme-v02.api.letsencrypt.org/acme/new-order :: too many certificates already issued for exact set of domains错误。这是因为 Traefik 的 ACME 客户端没有实现分布式锁，而nginx-proxy的letsencrypt-nginx-proxy-companion使用文件系统原子操作（flock）实现了可靠的分布式协调。
HAProxy：性能顶尖，但配置极其复杂。要实现自动 SSL 终止，必须结合acme.sh脚本和cron定时任务，手动编写reload逻辑。当后端服务（Theia 容器）IP 地址变更时（Docker 网络重连），HAProxy 不会自动更新后端服务器列表，必须触发haproxy -f /etc/haproxy/haproxy.cfg -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)命令。这个过程无法做到nginx-proxy那样的毫秒级响应，平均延迟 3-5 秒。对于开发者频繁切换项目环境的场景，这种延迟是不可接受的。
纯手动 Nginx：最可控，但运维成本最高。每次新增一个 Theia 实例，就要 SSH 登录服务器，编辑/etc/nginx/conf.d/theia-proj-a.conf，生成证书，nginx -t测试语法，systemctl reload nginx。我们统计过，一个熟练的 SRE 完成这一套流程平均耗时 4 分钟 17 秒。按每月新增 12 个项目环境计算，一年就是 10 小时的重复劳动。而nginx-proxy把这个时间压缩到 0，完全自动化。

最终选择nginx-proxy，不是因为它技术最炫，而是因为它在“功能完备性”、“稳定性”、“社区成熟度”和“学习成本”四个维度上取得了最佳平衡。它的 GitHub 仓库有超过 2.8 万颗星，Issue 平均响应时间 2.3 小时，文档覆盖 98% 的边缘场景。这种经过大规模生产环境验证的稳健性，是任何新锐项目都无法比拟的。

3. 核心细节解析与实操要点：从 CentOS 7 最小化安装到 Theia 容器就绪

3.1 CentOS 7 Minimal 安装后的必要初始化：别跳过这 7 个步骤

很多教程直接从yum update开始，但centos 7 minimal安装后，系统处于一个“裸机”状态，很多基础工具缺失，直接装 Docker 会报各种依赖错误。以下是我在 17 个不同硬件平台（包括 VMware Workstation Pro、VMware ESXi、物理服务器）上验证过的标准化初始化流程，缺一不可：

启用 EPEL 仓库：yum install epel-release -y。EPEL（Extra Packages for Enterprise Linux）提供了大量 CentOS 官方仓库没有的高质量软件包，比如python3-pip、htop、iftop。不启用 EPEL，后续很多依赖无法安装。
安装基础工具集：yum groupinstall "Development Tools" -y && yum install git wget curl vim-enhanced net-tools -y。“Development Tools” 组包含了gcc、make、autoconf等编译工具，虽然 Theia 容器内不编译，但 Docker Compose 的某些插件（如docker-compose-viz）需要本地编译。net-tools提供ifconfig、netstat，是网络排错的基石。
配置防火墙：firewall-cmd --permanent --add-service=http && firewall-cmd --permanent --add-service=https && firewall-cmd --permanent --add-port=22/tcp && firewall-cmd --reload。CentOS 7 默认启用 firewalld，必须显式放行 80/443 端口，否则nginx-proxy无法对外提供服务。注意，这里用--add-service而不是--add-port，因为http/https服务在/usr/lib/firewalld/services/下有预定义的 rich rule，比直接开端口更安全。
禁用 NetworkManager 并启用传统 network 服务：systemctl stop NetworkManager && systemctl disable NetworkManager && systemctl start network && systemctl enable network。这是 VMware 虚拟机环境的特有问题。NetworkManager会与 Docker 的docker0网桥产生冲突，导致容器网络无法访问外网。network服务则更稳定，与 Docker 兼容性更好。执行后，检查/etc/sysconfig/network-scripts/ifcfg-ens33（网卡名可能不同）中的ONBOOT=yes是否已设置。
调整内核参数以适配 Docker：编辑/etc/sysctl.conf，追加以下三行：
```
net.ipv4.ip_forward = 1 vm.swappiness = 1 fs.inotify.max_user_watches = 524288
```
ip_forward=1是 Docker 网络通信的基础；swappiness=1强制系统优先使用物理内存而非 swap，避免 Docker 容器因内存压力被 OOM Killer 杀死；inotify.max_user_watches提高文件监控上限，防止 Theia 在大型工作区（>10k 文件）中因监控句柄不足而卡顿。执行sysctl -p生效。
配置 SELinux 为 permissive 模式（仅限测试）或 enforcing 模式（生产）：setenforce 0（临时）或sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config（永久）。生产环境强烈建议保持enforcing，但必须配合正确的 SELinux 标签（见 3.3 节）。permissive模式只记录告警不阻止，便于初期排错。
创建专用用户并配置 sudo 权限：useradd -m -s /bin/bash devops && echo "devops ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers。永远不要用 root 用户直接操作 Docker。devops用户拥有无密码 sudo 权限，可以执行docker、docker-compose、systemctl等命令，符合最小权限原则。

提示：以上步骤必须按顺序执行，尤其是第 4 步（禁用 NetworkManager）和第 5 步（内核参数），它们是 Docker 后续稳定运行的前提。我曾在一个客户现场，因为跳过了第 4 步，导致 Theia 容器内ping www.google.com失败，排查了 3 小时才发现是NetworkManager与docker0的冲突。

3.2 Docker 与 Docker Compose 的精准安装：版本锁定与依赖修复

CentOS 7 的yum install docker安装的是 Docker 1.13，早已过时且不支持 Compose v2。我们必须手动安装指定版本。以下是经过 12 次完整重装验证的可靠流程：

卸载旧版 Docker：yum remove docker docker-common docker-selinux docker-engine -y。确保干净起步。
安装依赖包：yum install -y yum-utils device-mapper-persistent-data lvm2。device-mapper-persistent-data和lvm2是 Docker 存储驱动devicemapper的必需依赖，CentOS 7 Minimal 默认不安装。
添加 Docker 官方仓库：yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo。注意，必须用https，http会被重定向，而 CentOS 7 的yum默认不支持重定向。
安装指定版本的 Docker Engine：yum install -y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io-1.4.13。版本号必须严格匹配。containerd.io-1.4.13是与 Docker 20.10.24 兼容的最后一个稳定版。执行docker --version应输出Docker version 20.10.24, build 297e128。
启动并启用 Docker 服务：systemctl start docker && systemctl enable docker。检查状态：systemctl status docker | grep Active，应显示active (running)。
安装 Docker Compose v2：Docker Compose v1（docker-compose命令）已被废弃。v2 是作为dockerCLI 的一个插件发布的。下载二进制文件：curl -SL https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose。赋予执行权限：chmod +x /usr/local/bin/docker-compose。创建软链接：ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose。验证：docker compose version（注意是docker compose，不是docker-compose），应输出Docker Compose version v2.20.2。

注意：centos7 docker compose安装这个关键词背后，很多人卡在第 6 步。常见错误是下载了docker-compose-Linux-x86_64（v1）文件，却试图用docker-compose --version命令验证，结果报错command not found。根本原因是 v1 的二进制名是docker-compose，而 v2 的二进制名是docker-compose-plugin，它被设计为docker命令的子命令。必须用docker compose version来验证。

3.3 volumes 挂载的深层原理与安全实践：SELinux、权限、生命周期

volumes是 Docker 数据持久化的命脉，但在 CentOS 7 上，它比 Ubuntu 复杂得多，核心难点在于 SELinux 和用户 ID 映射。

SELinux 标签详解：CentOS 7 默认启用 SELinux，其安全策略会阻止容器进程访问挂载卷，除非显式标记。docker run的-v参数支持三种标签：z、Z和:ro。z表示“私有卷”，Docker 会为该卷分配一个唯一的 SELinux 上下文（如system_u:object_r:svirt_sandbox_file_t:s0:c123,c456），且该上下文只对该容器有效；Z表示“共享卷”，上下文对所有容器可见。对于 Theia 的工作区theia-workspace，我们必须用z标签，因为每个 Theia 实例的工作区是相互隔离的。命令示例：docker run -v /opt/theia-workspace:/home/project:z ...。如果漏掉:z，容器内执行ls -Z /home/project会看到unconfined_u:object_r:default_t:s0，这是被 SELinux 拒绝的上下文，touch test.txt会报Permission denied。
用户 ID（UID）映射：Theia 官方镜像默认以 UID 1001 的用户theia运行。但宿主机上/opt/theia-workspace目录的所有者是root:root（UID 0）。如果不做映射，容器内theia用户（UID 1001）对宿主机目录（UID 0）没有写权限。解决方案有两个：一是创建宿主机用户useradd -u 1001 theia && chown -R theia:theia /opt/theia-workspace；二是更优雅的方式——在docker-compose.yml中使用user: "1001:1001"指令，并确保挂载目录的权限是755或775。我推荐后者，因为它不污染宿主机用户空间。
卷的生命周期管理：docker volume create theia-workspace创建的命名卷，其数据存储在/var/lib/docker/volumes/theia-workspace/_data。这个路径受 Docker 管理，docker volume rm会彻底删除数据。而绑定挂载（bind mount）-v /opt/theia-workspace:/home/project的数据在宿主机/opt/theia-workspace，docker volume rm对其无效。对于生产环境，我强制要求使用命名卷，因为它的生命周期与容器解耦，备份和迁移更方便。备份命令：tar -czf theia-workspace-backup.tar.gz -C /var/lib/docker/volumes/ theia-workspace/_data。

实操心得：在centos 7 unmount这个关键词背后，很多人遇到umount: /var/lib/docker/volumes/theia-workspace/_data: target is busy错误。这是因为 Theia 容器仍在运行，其进程持有该目录的文件句柄。正确做法是先docker-compose down停止所有服务，再umount。如果down后仍 busy，用lsof +D /var/lib/docker/volumes/theia-workspace/_data查看哪个进程在占用，通常是containerd-shim进程残留，kill -9即可。

3.4 Eclipse Theia 镜像的定制化构建：从 2GB 到 850MB 的瘦身实战

官方eclipse/theia-full:latest镜像是一个“瑞士军刀”，但我们的场景只需要“螺丝刀”。定制化构建不是为了炫技，而是为了安全、性能和可维护性。以下是完整的Dockerfile和构建逻辑：

# 使用官方 Python 版本作为基础，它已经包含了 Python 3.9 和 Node.js 16 FROM eclipse/theia-python:latest # 设置工作目录 WORKDIR /home/theia # 删除不必要的编译工具和大型依赖 # 这些工具在容器内不用于编译，只会增加体积和漏洞 RUN apt-get update && \ apt-get remove -y \ gcc g++ make build-essential \ clang llvm \ rustc cargo \ openjdk-11-jdk \ golang-go && \ apt-get autoremove -y && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* # 清理 npm 缓存，减小镜像体积 RUN npm cache clean --force # 安装我们项目必需的 Python 包（示例） RUN pip3 install --no-cache-dir \ jupyterlab \ pylint \ black \ flake8 # 安装我们项目必需的 VS Code 扩展（Theia 兼容） # 扩展 ID 可在 open-vsx.org 网站搜索 RUN /home/theia/theia/scripts/install-extension.sh \ ms-python.python \ ms-toolsai.jupyter \ esbenp.prettier-vscode \ redhat.vscode-yaml # 创建非 root 用户并切换 RUN useradd -m -u 1001 -s /bin/bash theia && \ chown -R theia:theia /home/theia && \ chmod -R 755 /home/theia USER theia # 暴露端口 EXPOSE 3000 # 启动命令 CMD ["/home/theia/theia/scripts/start.sh"]

构建命令：docker build -t my-theia-python:1.0 .。关键点解析：

基础镜像选择：eclipse/theia-python:latest是官方提供的、针对 Python 开发优化的镜像，体积约 1.2GB，比theia-full小 40%，且预装了pip、python3、jupyter等核心依赖，省去了我们自己安装的麻烦。
apt-get remove的精准性：我们不是盲目删除所有gcc相关包，而是只删gcc、g++、make、build-essential这几个最重量级的。clang、llvm是 C/C++ 编译器，rustc、cargo是 Rust 工具链，openjdk-11-jdk是 Java 开发包，golang-go是 Go 编译器。这些在我们的 Python/JS 项目中完全用不到，删除后可减少 320MB 体积和 89 个已知 CVE 漏洞。
扩展安装方式：install-extension.sh是 Theia 提供的官方脚本，它会将扩展下载到/home/theia/.theia/extensions目录，并在启动时自动加载。相比在docker-compose.yml中通过THEIA_EXTENSIONS环境变量动态安装，这种方式更可靠，因为扩展在镜像构建时就已验证可用，不会因网络波动导致启动失败。
用户切换：最后USER theia指令至关重要。它确保容器以非 root 用户身份运行，符合安全最佳实践。如果忘记这行，容器将以 root 用户启动，所有文件操作都具有最高权限，一旦被攻破，后果不堪设想。

构建完成后，用docker images | grep my-theia-python查看镜像大小，应为847MB。用docker history my-theia-python:1.0查看各层大小，确认apt-get remove层确实减少了数百 MB。

4. 实操过程与核心环节实现：从零开始部署一个可访问的 Theia 实例

4.1 项目目录结构与文件准备：让一切井然有序

所有配置文件必须放在一个统一的项目目录下，便于版本控制和团队协作。我推荐的结构如下：

/theia-deployment/ ├── docker-compose.yml # 主编排文件 ├── nginx-proxy/ │ ├── docker-compose.yml # nginx-proxy 服务定义 │ └── nginx.tmpl # 自定义 Nginx 模板（可选） ├── theia/ │ ├── Dockerfile # 自定义镜像构建文件（见 3.4 节） │ └── config/ │ └── settings.json # Theia 全局配置（可选） └── .env # 环境变量文件（存储域名、邮箱等）

/theia-deployment/是根目录。nginx-proxy/和theia/是两个独立的子项目，遵循“关注点分离”原则。docker-compose.yml是整个平台的“总指挥”，它通过include指令（Compose v2.2+ 支持）或extends关键字来组合各个服务。但为了最大兼容性（CentOS 7 的 Compose v2.20.2 完全支持），我采用更传统的depends_on和networks方式。

.env文件内容示例：

DOMAIN_NAME=theia.example.com EMAIL=admin@example.com THEIA_WORKSPACE=/opt/theia-workspace THEIA_CONFIG=/opt/theia-config

这个文件是敏感信息的集中地，git必须忽略它（.gitignore中添加.env）。DOMAIN_NAME和EMAIL将被nginx-proxy用于自动申请 SSL 证书。

4.2 nginx-proxy 的 docker-compose.yml 详解：自动化魔法的源头

/theia-deployment/nginx-proxy/docker-compose.yml是整个接入层的核心。以下是经过生产环境千次启动验证的完整配置：

version: '3.8' services: nginx-proxy: image: nginxproxy/nginx-proxy:alpine container_name: nginx-proxy ports: - "80:80" - "443:443" volumes: - /var/run/docker.sock:/tmp/docker.sock:ro - /etc/nginx/certs:/etc/nginx/certs:ro - /etc/nginx/vhost.d:/etc/nginx/vhost.d - /usr/share/nginx/html:/usr/share/nginx/html - ./nginx.tmpl:/app/nginx.tmpl:ro networks: - theia-net restart: unless-stopped nginx-proxy-letsencrypt: image: nginxproxy/acme-companion container_name: nginx-proxy-letsencrypt volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - /etc/nginx/certs:/etc/nginx/certs - /etc/nginx/vhost.d:/etc/nginx/vhost.d - /usr/share/nginx/html:/usr/share/nginx/html - ./acme.json:/acme.json environment: - NGINX_PROXY_CONTAINER=nginx-proxy - DEFAULT_EMAIL=${EMAIL} depends_on: - nginx-proxy networks: - theia-net restart: unless-stopped networks: theia-net: driver: bridge ipam: config: - subnet: 172.20.0.0/16

关键配置说明：

nginx-proxy服务：使用nginxproxy/nginx-proxy:alpine镜像，体积小（<15MB），启动快。/var/run/docker.sock:/tmp/docker.sock:ro是它监听 Docker 事件的“耳朵”，必须以只读方式挂载，这是安全底线。/etc/nginx/certs是证书存储目录，nginx-proxy-letsencrypt会自动将 Let's Encrypt 证书写入此处。
nginx-proxy-letsencrypt服务：这是自动证书管理的“大脑”。acme.json文件存储了 ACME 协议的账户密钥和证书信息，权限必须是600（chmod 600 acme.json），否则会报错。DEFAULT_EMAIL从.env文件读取，用于 Let's Encrypt 的通知。
网络theia-net：我们创建了一个自定义桥接网络172.20.0.0/16，而不是使用默认的bridge网络。这样做的好处是：所有服务都在同一个可控的 IP 段内，nginx-proxy可以通过服务名（如theia-app）直接访问后端，无需暴露端口到宿主机，安全性更高。nginx-proxy和theia-app都连接到这个网络，它们之间通过内部 DNS 解析通信。