安装部署
端口与目录说明
Mopheus 部署后的端口占用与安装目录结构说明。
本文说明 Mopheus 部署后占用的端口和安装目录结构，适用于在线安装和离线安装。
端口总览
| 服务 | 默认端口 | 环境变量 | 对外暴露建议 |
|---|---|---|---|
| 前端（Web） | 3000 | FRONTEND_PORT | 浏览器访问入口；使用 Nginx 时可仅开放 Nginx 端口 |
| 后端（API） | 8080 | BACKEND_PORT | API / CLI / 守护进程入口；使用 Nginx 时可通过代理访问并限制直连 |
| PostgreSQL | 5432 | POSTGRES_PORT | 不建议暴露，仅限内网访问或配置防火墙规则 |
| SwissQL | 18080 | SWISSQL_PORT | 不建议暴露，包含管理端点（需 SWISSQL_ADMIN_TOKEN），仅限内网访问 |
服务地址（以 .env 中配置的地址为准）：
- Frontend:
http://<宿主机IP>:3000 - Backend:
http://<宿主机IP>:8080 - SwissQL:
http://<宿主机IP>:18080
注意事项：
- 修改端口后需重启服务（
./mopheus.sh restart）才能生效。 - 如端口被占用，容器启动时会报端口已被占用错误。
- PostgreSQL 和 SwissQL 端口如必须对外访问，请配置防火墙规则并确认已设置强密码 /
SWISSQL_ADMIN_TOKEN。
Nginx 反向代理
通过 Nginx 使用 HTTPS 域名访问时，需要将前端页面转发到 3000、API 和 WebSocket 转发到 8080。浏览器 WebSocket 使用 /ws，daemon WebSocket 使用 /api/v1/daemon/ws；两个 location 都必须使用 HTTP/1.1，并同时转发 Upgrade 和 Connection: upgrade 请求头，否则会出现 WebSocket upgrade 失败。
在 Nginx 的 server {} 中配置：
location /ws {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400s;
}
location = /api/v1/daemon/ws {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400s;
}
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}示例假设 Nginx 与 Mopheus 部署在同一台宿主机，端口使用默认值；跨主机或修改过端口时请替换 upstream 地址。.env 中的 FRONTEND_ORIGIN 和 CORS_ALLOWED_ORIGINS 也应设置为用户实际访问的 HTTPS 域名。
安装目录结构
安装目录由部署时决定（本文以 /app/mopheus 为例），所有持久化数据都在该目录下：
/app/mopheus/ # 安装目录（部署时自选）
├── .env # 配置文件（init-env 自动生成）
├── docker-compose.yml # 服务编排定义
├── data/ # 所有持久化数据（备份重点）
│ ├── pgdata/ # PostgreSQL 数据
│ ├── uploads/ # 上传文件（见下方对象存储说明）
│ ├── swissql_data/ # SwissQL 数据
│ ├── swissql_audit/ # SwissQL 审计日志
│ └── swissql_jdbc_drivers/ # SwissQL JDBC 驱动
├── images/ # 离线容器镜像（仅离线安装包包含）
├── logs/ # 服务日志
└── backups/ # 升级时的配置快照uploads/ 与对象存储
data/uploads/ 是默认的本地存储位置，上传的附件都保存在这里。
也可以在管理面板（管理 → 系统配置）中将存储切换为 S3 兼容的对象存储（支持 s3、oss、obs、cos、minio 驱动）。切换后上传文件不再写入 data/uploads/，而是保存到对象存储 Bucket，具体配置项和各云厂商的 Endpoint 格式参见管理面板 — 系统配置。
修改任意存储设置后需重启服务才能生效。
备份与迁移
所有持久化数据都在安装目录的 data/ 下：
- 备份：至少保留
data/整个目录和.env配置文件。 - 迁移：将整个安装目录复制到新服务器（路径可以不同），执行
./mopheus.sh start-server即可。 - 升级：升级脚本会在修改文件前自动创建配置快照到
backups/<旧版本>-<时间戳>/，data/中的数据不会被删除。