云团 SaaS 开发文档

阅读说明

这份文档面向购买源码并独立部署云团的商家。你可以把云团理解为一个可二次开发的应用运营平台：主系统负责登录、权限、上传、应用管理、订单和应用市场；每个业务应用放在 addons 目录下独立维护。

商家自研应用与平台应用使用同一套模块规范，但来源不同。商家自研应用属于本地站点资产，不需要远程平台授权；平台应用需要从平台应用市场购买或由平台授权后同步。

建议先完整跑通安装、后台登录、上传配置和远程平台绑定，再开始开发自研应用。这样开发时可以直接复用主系统提供的认证、权限、上传和应用管理能力。

安装部署

1. 准备运行环境

PHP 建议使用 8.1 或更高版本，并开启 fileinfo、openssl、pdo_mysql、mbstring、curl、zip 扩展。
数据库使用 MySQL 8 或兼容版本，字符集建议统一为 utf8mb4。
Web 服务可使用 Nginx，站点运行目录需要指向项目的 public 目录。
服务器需要允许 PHP 读写 runtime、public/uploads、addons 以及应用发布目录。

2. 创建数据库

先创建数据库，再导入安装脚本。数据库名可以按实际环境调整，默认示例为 yuntuan。

CREATE DATABASE `yuntuan` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

导入项目中的安装脚本：

mysql -uroot -p yuntuan < database/install.sql

3. 配置环境变量

在项目根目录维护 .env。独立部署商家版至少需要配置数据库、发行版本、授权密钥和远程平台地址。

APP_DEBUG = false
DB_TYPE = mysql
DB_HOST = 127.0.0.1
DB_NAME = yuntuan
DB_USER = root
DB_PASS = your_password
DB_PORT = 3306
DB_CHARSET = utf8mb4
DB_PREFIX = yt_

YUNTUAN_EDITION = merchant
YUNTUAN_PLATFORM_API_BASE = https://platform.example.com
YUNTUAN_LICENSE_PATH = license.json
YUNTUAN_AUTH_KEY = 请生成并妥善保存的对称加密密钥

4. 配置 Nginx

Nginx 站点根目录应指向 public，并把不存在的文件转交给 index.php，这样 MVC 页面、API 和 Vue 后台路由都能正常工作。

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

平台绑定与授权

商家独立部署后，第一次进入后台应先绑定远程平台账号。绑定成功后，本地会保存商家编号、商家账号、授权域名、源码授权状态和已授权平台应用列表。

源码授权

源码销售按域名和商家账号共同绑定。后台登录时会检查上次授权校验时间，超过 24 小时会重新请求平台校验。

应用授权

平台应用需要远程平台授权后才能同步和安装。商家自研应用不走平台授权，默认内置应用由源码随附。

不要通过直接修改本地数据库的 authorized_addons 来尝试开通平台应用。商家版最终会以签名授权文件和远程平台校验结果为准，平台应用安装和升级也会再次校验授权。

商家后台

商家后台访问路径为 /admin。后台前端使用 TypeScript、Vite、Vue3、TailwindCSS 和 Ant Design Vue 开发，构建后的文件部署在 public/admin，接口统一走 /api。

常用后台模块

平台概览：查看系统信息、应用类型统计和运行状态。
应用管理：管理已安装应用、同步远程平台应用、安装自研应用包、进入应用独立后台。
后台用户及权限：维护管理员账号、用户分组、后台菜单和分组权限。
系统设置：维护上传存储方式，本地、七牛云、阿里云、腾讯云等配置都从这里管理。
个人中心：维护当前账号昵称、头像和密码。

应用目录结构

每个应用都是一个独立模块，必须放在 addons 目录下。目录名就是应用标识，只允许小写字母、数字和下划线，并建议以业务名称命名。

addons/
└── demo_app/
    ├── manifest.json
    ├── route.php
    ├── install.sql
    ├── upgrade.sql
    ├── backend/
    │   ├── controller/
    │   │   └── api/
    │   ├── model/
    │   └── service/
    ├── frontend/
    │   ├── src/
    │   ├── package.json
    │   └── vite.config.ts
    └── public/
        └── admin/

目录职责

目录或文件	用途
`manifest.json`	应用清单，声明名称、版本、价格、支持平台、权限、菜单、接口前缀和打包规则。
`route.php`	应用独立路由，主系统启动时会自动加载 addons 下各应用的路由文件。
`backend`	应用 PHP 后端源码，包含控制器、模型、服务类等。
`frontend`	应用后台前端开发源码，仅开发阶段保留，发布应用包时不允许包含未构建源码。
`public`	应用构建后的前端和静态资源，安装时会发布到主站 public 下。

Manifest 清单

manifest.json 是应用被平台识别、安装和管理的核心文件。应用管理、安装器、远程同步都会读取它。

{
  "name": "demo_app",
  "title": "演示应用",
  "version": "1.0.0",
  "description": "用于演示商家自研应用开发规范。",
  "type": "system_plugin",
  "type_label": "系统插件",
  "source": "merchant_local",
  "market_visible": true,
  "merchant_market_visible": true,
  "default_installed": false,
  "icon": "/static/addons/demo_app/icon.svg",
  "price": 0,
  "support_platforms": ["merchant"],
  "backend_url": "/addons/demo_app/admin/",
  "api_prefix": "/api/addons/demo_app/admin",
  "permissions": [
    { "permission": "demo_app.manage", "title": "管理演示应用" }
  ],
  "menus": [
    {
      "title": "演示应用",
      "path": "/addons/demo_app/admin/",
      "permission": "demo_app.manage",
      "icon": "SettingOutlined",
      "sort": 10,
      "visible": true
    }
  ],
  "install": { "sql": "install.sql" },
  "upgrade": { "sql": "upgrade.sql" },
  "runtime": {
    "backend": true,
    "frontend": true,
    "php": ">=8.1",
    "yuntuan": ">=0.1.0",
    "frontend_source": "frontend"
  },
  "package": {
    "source": "frontend",
    "public": "public",
    "exclude": ["frontend/src", "frontend/node_modules", "frontend/**/*.map"],
    "include": ["manifest.json", "route.php", "install.sql", "upgrade.sql", "backend", "public"]
  }
}

关键字段说明

source：商家自研应用使用 merchant_local；平台应用使用 platform；远程同步到商家站点后的平台应用会变为 platform_remote。
market_visible：是否在平台应用市场展示。
merchant_market_visible：安装到商家站点后，是否进入商家面向普通用户的本地应用市场。
default_installed：是否随源码默认安装，例如自定义首页这类站点级系统插件。
support_platforms：声明应用适用的部署环境，商家自研应用固定填写 ["merchant"]，平台应用由平台端统一维护。

后端接口开发

应用后端建议按照控制器、服务类、模型分层。控制器只做认证、权限、参数接收和响应；业务逻辑写在服务类；数据库表操作写在模型或服务中。

路由示例

<?php

use think\facade\Route;

Route::get(
    'api/addons/demo_app/admin/setting',
    '\\addons\\demo_app\\backend\\controller\\api\\Setting@detail'
);

Route::put(
    'api/addons/demo_app/admin/setting',
    '\\addons\\demo_app\\backend\\controller\\api\\Setting@save'
);

控制器建议

应用接口可以继承主系统已有的 API 基础控制器，以复用 token 认证、权限校验和统一响应。
每个方法进入业务前先校验权限，例如 demo_app.manage。
接口只返回前端需要的字段，不要直接暴露数据库整行敏感字段。
异常提示统一使用中文，方便商家后台直接展示。

数据库表命名

应用表建议使用 yt_应用标识_业务名，例如 yt_demo_app_setting。这样卸载、排查和迁移时都能快速识别归属。

应用后台前端

应用后台前端仍使用 TypeScript、Vite、Vue3、TailwindCSS 和 Ant Design Vue。开发源码放在应用自己的 frontend 目录下，构建产物输出到应用自己的 public/admin。

Vite 配置重点

base 应设置为应用后台访问路径，例如 /addons/demo_app/admin/。
outDir 应输出到 addons/demo_app/public/admin。
请求接口统一使用应用自己的 api_prefix，例如 /api/addons/demo_app/admin。

pnpm install
pnpm build

发布到应用商店或交付给商家安装时，不要包含 frontend/src、node_modules、源码映射文件和 TypeScript 构建缓存。只发布 PHP 后端、manifest、SQL、路由和 build 后的前端产物。

上传与资源

主系统提供统一上传能力，应用可以调用公共上传组件和上传接口。数据库中建议保存资源编号，而不是保存完整 URL。

为什么保存资源编号

本地存储和云存储都可以通过同一个资源编号生成最终访问地址。
云存储更换域名后，只需要更新上传配置，不需要批量修改业务表。
资源表可以记录文件类型、大小、驱动、对象路径和创建时间，便于后续清理。

支持的存储方式

本地上传七牛云直传阿里云 OSS 直传腾讯云 COS 直传

图片、视频、音频和附件都应走统一上传入口。当前后台优先使用图片选择器，后续应用需要其他文件类型时，保持相同接口协议即可。

权限与菜单

应用后台是独立入口，但仍建议使用主系统的后台账号和权限体系。应用权限写在 manifest 的 permissions 中，应用菜单写在 menus 中。

权限标识建议使用 应用标识.动作，例如 demo_app.manage。
菜单路径建议指向应用独立后台，例如 /addons/demo_app/admin/。
平台后台和商家后台的主菜单不应直接塞入应用内部页面，应用后台应该在新标签或独立入口打开。
如果应用需要多级权限，可以在应用内部继续维护自己的功能菜单，但接口权限仍应回到主系统统一校验。

打包发布

商家自研应用可以在本地打包后通过商家后台“安装应用”上传。平台应用则由平台后台上传版本安装包，商家授权后再同步安装。

发布前检查清单

确认 manifest.json 中的 name 与应用目录名完全一致。
确认 backend_url 和 api_prefix 都绑定当前应用目录。
执行前端 pnpm build，确保 public/admin 存在入口文件。
确认安装 SQL 可重复执行，不要破坏已有数据。
确认压缩包不包含未构建前端源码、node_modules、调试日志和本地密钥。

应用市场规则

云团同时支持平台自营应用市场和商家独立部署后的本地应用市场。两者展示规则不同，需要在开发应用时提前确认。

场景	展示规则	适用应用
平台应用市场	应用已安装、启用、上架、审核通过，并且 `market_visible=1`。	平台上架售卖或免费分发的应用。
商家本地应用市场	商家自研应用或已授权远程平台应用，并且 `merchant_market_visible=1`。	商家面向普通用户售卖或开放使用的应用。
默认内置应用	随源码默认安装，可在商家后台应用管理中使用，但可以不进入商家本地应用市场。	自定义首页、站点配置、系统工具等站点级应用。

安全建议

生产环境关闭 APP_DEBUG，避免暴露错误堆栈和调试入口。
YUNTUAN_AUTH_KEY、数据库密码、云存储密钥等只放在服务器环境配置中，不要提交到应用包。
应用接口必须校验登录态和权限，不能只依赖前端菜单隐藏。
上传文件必须限制类型、大小和存储目录，前端直传完成后仍要回调服务端登记资源。
商家版不要通过本地数据库直接伪造平台应用授权，安装、同步和升级流程都应依赖远程授权。

常见问题

刷新后台页面 404

确认 Nginx 已配置 try_files $uri $uri/ /index.php?$query_string;，并且主系统路由中存在后台前端兜底入口。

接口返回 404

确认应用的 route.php 已放在应用目录下，并且路由前缀与 manifest.json 中的 api_prefix 一致。

应用后台空白

确认应用前端已经 build，入口文件和静态资源在 public/admin 内，且 Vite 的 base 与访问路径一致。

上传后的图片换域名失效

业务表应保存上传资源编号，由接口根据当前上传配置生成完整 URL。如果保存了旧域名完整路径，换域名后就需要手动迁移历史数据。

开发文档