上云 API 2 二次开发 Demo 部署指南

为了帮助开发者更快上手上云 API 2，上云 API 2 为开发者提供了二次开发 Demo - 上云 API 2 无人机管理平台。

下载上云 API 2 无人机管理平台源码。

形态	适用场景	复杂度	前置依赖
普通机器	单机/小规模，已有物理机或虚拟机	中	JDK17、MySQL8、nginx、systemd
Docker Compose	单机容器化，便于迁移与版本管理	低	Docker 24+、Docker Compose v2
Kubernetes	生产级高可用、多副本、弹性伸缩	高	K8s 集群、镜像仓库

推荐路径：安装部署 AI Plugin 后基于 AI 引导完成，无需逐节阅读。

1. 概览#

1.1 架构#

                    ┌──────────────┐
   用户 ──80/443──▶ │  fh-ui       │  Nginx + Vue 3 dist（端口 80）
                    └──────┬───────┘
                           │ /pf-devkit/ai-plugin/skeleton/* → proxy
                           ▼
                    ┌──────────────┐
                    │  skeleton    │  Spring Boot（端口 8080，context-path=/pf-devkit/ai-plugin/skeleton）
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼                         ▼
        ┌──────────┐            ┌──────────────┐
        │  mysql   │            │  MCP Server  │（独立部署，Chat 启用时需要）
        └──────────┘            └──────────────┘

1.2 平台限制#

1.3 外部依赖#

2. 前置准备#

2.1 获取源码#

2.2 安装构建工具#

使用 §3 AI 辅助部署时，Skill 会自动检测工具环境并引导安装缺失项。

3. 【推荐】AI 辅助部署#

快速完成部署：安装部署 Skill 后，AI 会根据你的环境自动引导完成构建、配置、启动、验证全流程——无需逐节阅读本文档。

3.1 安装部署 Skill#

方式 A：Plugin 一键安装（推荐，需 Claude Code >= 1.0）#

方式 B：手动配置 settings.json#

{
  "enabledPlugins": {
    "cloudapi2@dji": true
  },
  "extraKnownMarketplaces": {
    "cloud-api2": {
      "source": {
        "source": "directory",
        "path": "/path/to/dji-cloudapi2-skills"  // 替换为仓库绝对路径
      }
    }
  }
}

方式 C：手动拷贝（仅部署 Skill）#

3.2 启动 AI 引导部署#

帮我把 skeleton 部署到 Docker Compose

3.3 验证 Skill 已生效#

不用 AI？ 继续阅读 §4 的手动部署步骤。

4. 手动部署#

以下按三种部署形态分节说明。选择适合你环境的形态，跳过其余。

4.1 普通机器（JDK + MySQL + nginx + systemd）#

适用：单台 Linux x86_64 物理机/虚拟机。无需 Docker。

安装私有 SDK JAR（构建机一次性操作）#

Docker/K8s 部署无需此步——Dockerfile 多阶段构建已内置 JAR 安装。

安装运行时与依赖#

构建#

生成密钥与密码#

初始化数据库#

首次启动后 JPA ddl-auto=update 会自动建表。生产建议改用 validate + 迁移脚本管理 schema。

部署后端#

配置环境变量并注册 systemd#

部署前端并配置 nginx#

验证#

4.2 Docker Compose#

适用：单机容器化，首选推荐，镜像由您自行构建。

构建并推送镜像#

平台：后端镜像需 --platform linux/amd64（SDK native lib 仅 amd64）。Apple Silicon 加 DOCKER_DEFAULT_PLATFORM=linux/amd64。

配置 .env#

启动#

验证#

快速开始（本地 mock）#

4.3 Kubernetes#

适用：生产级高可用、多副本、弹性伸缩。Manifest 位于 skeleton/deploy/k8s/。

准备镜像#

编辑 Secret 与 ConfigMap#

应用#

验证#

TLS 与域名（可选）#

滚动升级与回滚#

5. MCP Server 部署（Chat功能依赖，可选）#

5.1 为什么需要#

5.2 Docker 形态#

5.3 K8s 形态#

GLIBC_TUNABLES=glibc.rtld.execstack=2 解决 glibc 2.39+ 拒绝 execstack .so 的问题。生产 Secret 化敏感变量。

5.4 与 skeleton 联调#

6. 环境变量全表#

6.1 后端必填#

6.2 后端可选#

6.3 前端#

7. 升级与回滚#

7.1 普通机器#

7.2 Docker#

7.3 Kubernetes#

数据库 schema 演进由 JPA ddl-auto=update 自动加列（不删列/改类型）。生产建议改 validate + Flyway/Liquibase。

8. 常见问题与故障排查#

8.1 常见问题#

8.2 故障排查#

9. 清理部署（卸载）#

清理 = 停止服务 + 移除运行态资源 + 按需删除数据。三形态命令互不影响，按实际部署形态选择。
危险操作确认原则：删除数据（数据卷 / PVC / 数据库）、删除镜像、删除 systemd unit 与配置目录均为不可逆操作，执行前必须与用户确认是否保留数据。

9.0 清理前准备#

9.1 普通机器（JDK + MySQL + nginx + systemd）#

9.2 Docker Compose#

注：skeleton/docker/docker-compose.yml 内置 skeleton + fh-ui 两服务；mysql 容器与 mysql-data 命名卷在 skeleton/deploy-compose.yml（deploy.sh 同步远端为 docker-compose.yml）。

down 只移除容器与默认网络，不删除命名卷 mysql-data；down -v 才会删除卷与其中数据。

9.3 Kubernetes#

kubectl delete namespace fh-skeleton 会级联删除该命名空间下的 全部 资源（含 PVC、Secret、ConfigMap）。仅需"停止保留数据"时，systemd/Docker 形态可选择性保留数据卷；K8s 的持久数据在 PVC（按 storageClass 默认 ReclaimPolicy=Delete 可能一并回收，按集群配置确认）。

附录 A：常用命令#