Docker 部署

Docker Compose 是部署 EasyShell 的推荐方式。所有服务（Server、Web、MySQL、Redis）均已完整容器化，预构建镜像通过 GitHub Actions 自动发布到 Docker Hub 和 GHCR。

前置条件

Docker 24.0 或更高版本
Docker Compose v2（Docker Desktop 已内置）
至少 4 GB 内存 用于完整技术栈
10 GB 可用磁盘空间

验证安装：

docker --version
docker compose version

快速部署

git clone https://github.com/easyshell-ai/easyshell.git
cd easyshell
cp .env.example .env      # 按需修改
docker compose up -d

无需本地构建 —— 预构建镜像会自动从 Docker Hub 拉取。

访问 http://localhost:18880，使用 easyshell / easyshell@changeme 登录。

服务架构

docker-compose.yml 定义了以下四个服务：

服务	镜像	端口	说明
easyshell-server	`laolupaojiao/easyshell-server:latest`	`18080`	Java Spring Boot 后端 + 内置 Agent 二进制
easyshell-web	`laolupaojiao/easyshell-web:latest`	`18880`	React 前端（Nginx 托管）
easyshell-mysql	`mysql:8.0`	`13306`	数据库
easyshell-redis	`redis:7-alpine`	`16379`	缓存

服务间依赖关系：web → server → mysql + redis，Docker Compose 通过健康检查确保启动顺序。

环境配置

.env.example 包含所有可配置项，复制为 .env 后修改：

# MySQL
MYSQL_PASSWORD=18923ce29fdab04e
MYSQL_DATABASE=easyshell
MYSQL_PORT=13306

# Redis
REDIS_PORT=16379

# Server
SERVER_PORT=18080
JAVA_OPTS=-Xms256m -Xmx512m

# Agent 连接地址（部署 Agent 时改为服务器外部可达 IP）
# PROVISION_SERVER_URL=http://your-server-ip:18080

# Web
WEB_PORT=18880

# 安全配置（生产环境务必修改！）
# JWT_SECRET=your-production-jwt-secret-key-must-be-at-least-64-characters-long-change-me
# ENCRYPTION_KEY=your-production-aes256-key!!

# Docker 镜像源（默认 Docker Hub，取消注释切换到 GHCR）
# EASYSHELL_SERVER_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-server:latest
# EASYSHELL_WEB_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-web:latest

验证服务

docker compose ps
docker compose logs easyshell-server
docker compose logs easyshell-web

所有服务应在 1–2 分钟内显示 healthy 状态。

开发环境

如需从源码构建（用于开发调试），使用开发配置文件：

docker compose -f docker-compose.build.yml up -d

这将使用本地的 Dockerfile.server 和 Dockerfile.web 构建镜像，而非拉取远程预构建镜像。

生产环境

安全加固

生产部署时的必要配置：

修改所有默认密码 —— MYSQL_PASSWORD、JWT_SECRET、ENCRYPTION_KEY
设置 PROVISION_SERVER_URL —— 改为服务器外部可达地址
限制端口暴露 —— MySQL（13306）和 Redis（16379）端口仅供调试使用，生产环境建议通过防火墙限制访问或移除端口映射
配置反向代理 —— 使用 Nginx 提供 TLS 终止，参见生产环境部署

资源限制

生产环境建议的资源配置：

服务	内存限制	CPU 限制
Server	1 GB	2.0
Web	256 MB	0.5
MySQL	1 GB	1.0
Redis	256 MB	0.5

数据持久化

所有数据存储在命名的 Docker 卷中：

easyshell_mysql_data —— 数据库文件
easyshell_redis_data —— Redis AOF 持久化

在生产环境中定期备份这些卷。查看安全配置了解自动备份脚本。

升级

升级 EasyShell 到新版本：

docker compose pull
docker compose up -d

Server 在启动时自动处理数据库迁移。