1. 整体说明

本文档用于指导服务器管理员将秒哒导出的应用安装包部署到自有 Linux 服务器。安装分为三步：

11. 将应用安装包上传到服务器。
22. 在服务器上安装 `miaoda-deploy` 部署工具。
33. 使用 `miaoda-deploy install` 安装应用。

服务会占用以下端口：

这两个端口是默认值。如果服务器上已有程序占用，可以在安装时用 --proxy-port 和 --studio-port 改成别的宿主机端口。

2. 支持的环境

2.1 服务器类型

支持能够正常运行 Docker Engine 的 Linux 物理服务器或云服务器，例如百度智能云 BCC，以及其他云厂商的Linux 云主机。服务器需满足以下条件：

• 操作系统为 64 位 Linux。
• CPU 架构为 x86_64/amd64。
• 能够安装并运行 Docker Engine。
• 当前用户具有 sudo 权限，或者已经具有 Docker 和安装目录的操作权限。

不支持 Windows、macOS、32 位 Linux、ARM64/aarch64 本机 Docker 部署，以及不能运行 Docker 的受限容器环境。常见的 Ubuntu、Debian、CentOS Stream、Rocky Linux、AlmaLinux 等发行版通常都可以使用，具体版本应同时满足 Docker Engine 的官方支持范围。

检查操作系统和 CPU 架构：

1uname -s
2uname -m

输出的操作系统应为 Linux，架构应为 x86_64。如果输出 aarch64 或 arm64，当前版本不能使用本机 Docker 模式。

2.2 CPU、内存和磁盘

下表是综合应用运行、前端构建和镜像资源消耗给出的部署建议，不是程序内置的硬性阈值。实际资源会由应用与服务器上的其他进程共享。

3. 安装前准备

3.1 必需软件

服务器需要提前准备：

安装后确认 Docker 可用：

1docker --version
2docker info

如果 docker info 提示权限不足，请使用具备 Docker 权限的账号执行安装，或按照 Docker 官方文档将当前用户加入 docker 用户组。用户组变更通常需要重新登录后生效。

3.2 网络要求

服务器需要具备正常的 DNS 解析能力，并允许以下出站访问：

• 通过 HTTPS 访问 miaoda-public.bj.bcebos.com，用于下载安装部署工具。
• 访问应用前端依赖使用的软件源，例如系统软件源和 npm/pnpm 软件源。

如果反向代理与应用部署在同一台服务器，不建议在防火墙或云安全组中直接向公网开放 8090 和 8089。

3.3 域名和反向代理

安装过程中必须输入完整的外网访问地址，地址需要包含 http:// 或 https://，例如：

1http://domain.com
2https://domain.com
3https://10.224.55.18:8090

这里通常应填写浏览器实际使用的公共地址。也允许使用 0.0.0.0、127.0.0.1 或 localhost 完成本机部署，但这些地址只适合本机访问。需要让其他机器访问时，请填写实际使用的域名或服务器 IP。

执行安装前，请完成以下准备：

1. 将域名解析到服务器公网 IP 或前置负载均衡的公网 IP。
2. 如果使用 HTTPS，在反向代理或负载均衡上配置有效的 TLS 证书。
3. 将该访问地址收到的应用请求转发到部署服务器的 127.0.0.1:8090。
4. 确保反向代理支持 WebSocket，并保留 Host、X-Forwarded-For 和 X-Forwarded-Proto 请求头。

1# 以下是应用域名使用 HTTP 时的 Nginx 配置示例：
2
3server {
4    listen 80;
5    server_name domain.com;
6    client_max_body_size 100m;
7
8    location / {
9        proxy_pass http://127.0.0.1:8090;
10        proxy_http_version 1.1;
11        proxy_set_header Host $host;
12        proxy_set_header X-Real-IP $remote_addr;
13        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
14        proxy_set_header X-Forwarded-Proto $scheme;
15        proxy_set_header Upgrade $http_upgrade;
16        proxy_set_header Connection "upgrade";
17        proxy_read_timeout 3600s;
18    }
19}
20
21# client_max_body_size 应根据应用允许上传的最大文件调整。
22# 使用 HTTPS 时，应在 listen 443 ssl 的虚拟主机中配置证书，并将请求继续转发到http://127.0.0.1:8090。安装时则输入 https://domain.com。

8089 是 Studio 管理端口，不是应用主入口。访问 Studio 需要使用安装时设置的管理账号和密码。如需远程使用 Studio，仍建议使用单独的管理域名、IP 白名单或 VPN，不要直接暴露到公网。

3.4 短信服务配置（可选）

注：如果你的应用使用了短信验证码登录功能，则一定需要配置。

短信服务用于注册、登录和找回密码等短信验证码场景。配置前请在百度智能云控制台完成以下准备：

1. 开通短信服务并完成账号实名认证。
2. 在访问控制中创建用于发送短信的访问密钥，获取 Access Key（AK）和 Secret Key（SK），并按最小权限原则授权。
3. 创建短信签名和短信模板，提交审核并等待审核通过。
4. 记录审核通过后的签名 ID 和模板 ID。模板内容应包含应用实际发送的验证码变量。

安装时选择配置短信服务，并按提示填写：

短信配置为可选项。跳过配置不会影响应用安装，但短信验证码功能不可用；密钥不会在 CLI 日志中显示。短信服务的具体资费、频控和审核要求以百度智能云控制台当前规则为准。

3.5 邮件服务（SMTP）配置（可选）

注：如果你的应用使用了邮箱登录功能，则一定需要配置。

邮件服务用于账号确认、密码找回和系统通知等邮件场景。请向企业邮箱管理员或邮件服务商申请 SMTP 发送权限，并提前确认：

1. SMTP 主机地址和端口。常见端口为 465（SSL）或 587（STARTTLS），以服务商要求为准。
2. SMTP 用户名，通常是完整邮箱地址。
3. SMTP 密码或专用授权码。部分邮箱不允许使用网页登录密码，必须单独生成 SMTP 授权码。
4. 管理员邮箱，用于接收系统管理邮件。
5. 发件人名称，以及服务商要求的发件人认证或域名配置（如 SPF、DKIM）。

安装时选择配置邮件服务，并按提示填写：

邮件配置为可选项。跳过配置不会影响应用安装，但账号确认、密码找回和邮件通知不可用；密码或授权码不会在 CLI 日志中显示。配置完成后，请确认服务器允许访问 SMTP 服务商的出站端口。

4. 上传应用安装包

首先在秒哒平台下载应用部署包，保存到本地。

然后使用云服务器控制台提供的文件上传功能，将应用部署包上传到服务器当前用户的 Home 目录：

1scp app-e00dqck402dd.tar.gz <服务器用户>@<服务器IP>:~/

5. 安装部署工具

在目标服务器上执行：

1curl -fsSL https://miaoda-public.bj.bcebos.com/miaoda-deploy-cli/installer.sh | bash

安装后检查命令：

1miaoda-deploy --help

后续升级部署工具时执行：

1miaoda-deploy upgrade

6. 安装应用

1miaoda-deploy install PATH_TO_data.tar.gz

安装默认按照归档中的应用类型自动编译前端并部署后端，不会询问是否跳过前端。只需要恢复后端数据时可显式执行：

按照终端提示依次完成配置：

1. 部署模式选择“本机 Docker 安装”。
2. 确认实例目录。交互式安装未传参数时会始终询问，回车复用当前用户配置目录，也可输入新目录。
3. 输入完整的外网访问地址，例如 https://domain.com。
4. 根据实际情况选择是否配置短信服务和邮件服务；不使用时可以跳过。

5. 如果检测到已有目标目录、未完成安装残留、未注册的同名容器，或本次选择了不同于当前活动实例的新目录，认真阅读覆盖/切换警告后再决定是否继续。输入完成后，工具会自动执行以下工作，无需再手工导入数据：

   • 安全解压并检查应用安装包。
   • 判断并编译 Vite、Taro 或 Expo Web 前端。
   • 生成 Supabase 密钥和运行配置。
   • 检查运行配置并准备应用目录。
   • 拉取 All-in-One 镜像并启动应用。
   • 恢复应用数据。
   • 等待各服务健康检查通过并写入安装成功状态。
   • 保存实例信息，供后续管理命令自动定位。

默认的 8090 / 8089 已被其他程序占用时，可以改用别的宿主机端口：

1miaoda-deploy install app.tar.gz --target docker --proxy-port 19090 --studio-port 19082

--proxy-port 和 --studio-port 只改变宿主机访问端口，默认使用 8090 和 8089。两个端口必须不同，且不能被其他程序占用。

安装过程中不要关闭 SSH 会话或终止命令。前端依赖下载、Docker 镜像拉取和数据库恢复耗时取决于网络速度及应用数据量。

重要： 数据目录是该应用的专用目录。同目录重新安装会在确认后清理原有数据；选择新目录会在确认后替换 当前活动容器，但旧目录默认保留。安装失败时，工具会清理本次安装创建的容器和目标目录；不要在数据目录中 存放其他文件，清理失败安装残留前应先确认其中没有需要保留的数据。

7. 验证安装结果

安装成功后，终端会显示应用 ID、数据目录和访问地址。

1╔══════════════════════════════════════════════════════╗
2║                       安装完成                        ║
3╚══════════════════════════════════════════════════════╝
4  应用 ID  : app-e00dqck402dd
5  数据目录 : /home/alice/miaoda_deploy
6  访问地址 : https://my-app.com
7  API 端口 : 8090
8  Studio  : 8089

最后在浏览器中访问安装时输入的完整地址，例如：

1https://my-app.com

能够打开应用，且登录、数据库读写、文件上传等实际业务功能正常，才表示部署和公网转发均已完成。

8. 常见问题

8.1 无法执行 Docker

现象通常为“未检测到 Docker”或“无法连接 Docker 服务”。请检查：

1systemctl status docker
2docker info

确认 Docker 服务已启动，并且当前用户有权使用 Docker。

8.2 8090 或 8089 端口被占用

查找占用端口的进程：

1ss -ltnp | grep -E ':(8090|8089)[[:space:]]'

停止或调整冲突服务后，重新执行安装。也可以保留原有服务，安装时用 --proxy-port / --studio-port 换成空闲的宿主机端口，并把反向代理指向新的 API 端口。

8.3 Docker 镜像拉取失败

如果服务器架构为 aarch64/arm64，工具会直接提示当前镜像仅支持 Linux amd64；这不是网络或权限问题，请改用 amd64 主机或 External 模式。不要在 ARM64 主机上反复执行安装、更新、备份或恢复命令。

8.4 安装成功但域名无法访问

先从服务器本机检查应用入口：

1curl -I http://127.0.0.1:8090/

本机访问正常而域名访问异常时，重点检查 DNS、云安全组、防火墙、TLS 证书和反向代理配置。确认反向代理上游是127.0.0.1:8090，并且安装时输入的协议和域名与浏览器访问地址一致。

8.5 安装失败或服务启动异常

查看应用状态和日志：

1miaoda-deploy status

如仍异常，请根据安装命令最后显示的具体错误排查 Docker、网络、前端依赖或安装包问题，然后重新执行完整安装。如果覆盖安装时提示实例目录中的文件没有权限删除，请确保当前用户具有该目录的操作权限，或按提示使用 sudo 完成清理。

9. 日常运行注意事项

• update、config、start、stop、status 和 doctor 会自动读取已保存的实例信息。
• 不要手工删除实例目录中的配置或状态文件。
• 服务器重启后应检查应用状态；如应用未自动启动，可执行 miaoda-deploy start。
• 对外只开放业务所需入口，Studio 管理端口应受到严格访问控制。