shopagg-b2b-website

---

项目简介

SHOPAGG CMS 是一套面向 B2B 外贸业务的开源官网系统，将产品展示、内容运营、客户询盘、主题外观和插件扩展整合在一个轻量应用中。核心程序使用 PHP 8.1+ 与 SQLite3，不依赖 Composer 包，适合部署到普通虚拟主机、VPS 或企业自有服务器。

SHOPAGG（中文名：思普艾格）是主品牌，开源程序正式名称为 SHOPAGG CMS，日常简称 SHOPAGG。可自行部署，也可通过 SHOPAGG 建站平台 自动部署。

想先了解产品定位和完整能力，请访问：

• SHOPAGG CMS 官网
• 32 项产品能力清单
• 在线演示站
• 当前稳定版与下载信息

核心能力

领域	主要能力	进一步了解
产品与商品	分类、图集、四种价格模式、多规格 SKU、软删除	产品管理文档
内容与媒体	文章、案例、独立页面、富文本、媒体库	内容与外观文档
询盘与线索	联系留言、产品询盘、处理状态、CSV 导出	询盘与日常运营
主题与外观	主题切换、可配置区块、菜单、轮播图	主题开发文档
插件与扩展	路由、事件、过滤器、服务、任务、后台页面	插件开发文档
应用商店	浏览、安装和升级插件及主题	设置与扩展
运维与更新	GitHub Release 更新、更新前备份、迁移、日志	运维文档
权限与安全	Staff 权限、CSRF、上传校验、安全响应头	安全边界
SEO 与国际化	SEO 字段、Sitemap、Open Graph、249 种在线翻译语言	完整能力清单

完整且可检索的功能状态以官网的产品能力清单为准，也可以直接读取产品能力 JSON。

界面预览

访问 demo.shopagg.org 体验前台页面；后台功能和操作流程可从使用文档了解。

前台

后台

仪表盘	产品管理

媒体库	系统设置

快速开始

运行环境

项目	要求
PHP	8.1 或更高版本
PHP 扩展	sqlite3、mbstring、fileinfo
Web 服务器	Apache（启用 mod_rewrite）或 Nginx
可写目录	storage/、uploads/

最新兼容性信息可读取兼容性 JSON。完整的 Apache、Nginx 和生产环境配置见安装与入门。

安装

git clone https://github.com/zhpelo/shopagg-b2b-website.git
cd shopagg-b2b-website
chmod -R 755 storage uploads

将站点根目录指向项目目录，然后访问网站。系统会自动创建 SQLite 数据库并执行待处理迁移。

后台默认入口为 /admin/login。初始账号通常为 admin / admin123，首次登录后请立即修改密码。

安装完成后建议继续阅读：

1. 首次登录与初始化
2. 产品管理与价格模式
3. 内容、菜单、轮播与主题外观
4. 插件、员工权限和程序更新
5. 上线检查与常见问题

技术设计

• 纯 PHP MVC：单入口、集中路由、控制器、模型和视图分层。
• SQLite3：站点数据默认保存在 storage/site.db，数据库结构通过迁移演进。
• 主题系统：前台主题位于 themes/{theme}，内容区块可在后台维护。
• Plugin API 1.0：Manifest 驱动的插件运行时，支持缓存、隔离数据、任务和服务契约。
• 可迁移部署：不绑定特定云平台，可部署到 Apache、Nginx 和常见 PHP 主机。

深入阅读：系统架构 · 数据模型 · 应用开发

目录结构

shopagg-b2b-website/
├── index.php               # 应用入口
├── app/
│   ├── Controllers/        # 前后台控制器
│   ├── Core/               # 路由、数据库、认证、迁移等核心模块
│   ├── Models/             # SQLite 数据模型
│   ├── Plugins/            # Plugin API 1.0 运行时
│   ├── Migrations/         # 核心数据库迁移
│   ├── views/admin/        # 后台页面
│   └── routes.php          # 路由注册
├── themes/                 # 前台主题
├── plugin-dev/             # 本地插件开发目录
├── plugin-assets/          # 已发布的插件静态资源
├── storage/                # 数据库、缓存、备份和日志
├── uploads/                # 用户上传文件
└── shopagg                 # CMS 命令行工具（开发与自动化）

插件与主题开发

业务扩展优先使用 Plugin API，避免直接修改核心文件。

SHOPAGG CMS 命令行工具面向插件开发者与托管自动化。普通用户通过后台管理插件即可，无需使用命令行。在 CMS 根目录运行 php shopagg help 查看命令；它与主机管理面板的 shopagg 命令是两个不同的工具。

插件开发流程：

php shopagg plugin:make my-plugin
php shopagg plugin:validate plugin-dev/my-plugin
php shopagg plugin:pack plugin-dev/my-plugin

plugin:validate 检查插件结构、PHP 语法，并在环境满足要求时加载插件类校验接口契约；不会执行插件业务功能测试。plugin:test 保留为同一校验命令的兼容别名。请检查输出中的 warnings：校验通过不代表类契约检查一定已执行。

托管自动化和运维可使用以下命令。请以站点所属用户运行，避免生成站点无法写入的文件：

php shopagg plugin:install /path/to/plugin.zip
php shopagg plugin:enable my-plugin
php shopagg plugin:disable my-plugin
php shopagg plugin:jobs 10

plugin:jobs 可接入系统定时任务，执行已到期的插件任务，无需依赖网站访问触发。CLI 默认关闭调试，与网页入口 index.php 共用版本信息；升级程序时无需单独修改 CLI 版本号。

插件使用固定安装目录 storage/plugins/{plugin-id}/，版本号保存在 plugin.json 和数据库中。上传 ZIP 或使用 plugin:install 会直接替换已有插件并保留启停状态；新插件需手动启用。同版本也可重装，站点不保留可切换的历史安装版本。更新会完整替换代码和发布资源，移除新包不再包含的旧文件；静态资源通过 ?ver= 刷新缓存。

每次进入后台插件管理页会核对本地目录，并静态校验、同步 plugin.json 中的名称、版本、描述、自动加载、生命周期入口、路由、菜单等注册信息，重建运行缓存，无需重复上传 ZIP。原启停状态、安装来源、设置、队列和业务数据保留；已启用插件同步后若环境、依赖或路由校验不通过，会自动停用。新插件登记为未启用；目录或清单缺失、清单无效、PHP 语法错误或入口文件缺失时保留最后有效清单并停用，不执行停用钩子。恢复目录后需手动启用。扫描不会自动加载插件类、执行生命周期或数据库迁移；有迁移/资源发布需求的代码更新仍使用安装流程。目录和插件 ID 改名按旧插件失效、新插件发现处理，不自动迁移身份或密钥。

安装、更新和启用时的代码、资源与数据库恢复文件只保留在本次操作的临时目录中；操作成功或恢复成功后清理。恢复失败时保留目录并报告路径。已启用插件更新会执行新增迁移和同步定时任务，不会重复调用 activate()。恢复只覆盖操作中捕获的异常，不保证发现更新后页面上的所有运行错误。安装前可在独立 CLI 进程运行 plugin:validate 检查类契约（需满足插件环境要求）。

升级到此布局时，系统自动将旧的版本目录迁移为固定目录：已启用插件保留实际运行版本，其他插件保留已安装版本；迁移成功后移除旧版本树。升级前请备份 storage/site.db、storage/plugins/ 和 assets/plugins/。已有历史数据库备份不会自动删除。

• 插件开发完整指南
• 主题目录、区块字段和安全输出规范
• 控制器、模型、迁移和后台页面开发
• 安全边界与发布前检查

开发与验证

正式发行包已经包含后台所需的编译后 CSS。只有修改后台 Tailwind 类名或 assets/admin/style.css 时，才需要 Node.js：

npm ci
npm run build:admin-css

提交 PHP 改动前，至少运行相关语法检查；修改后台导航后可运行现有冒烟测试：

php tests/admin_navigation_smoke.php

插件安装、更新与恢复流程可在隔离的临时目录中验证：

php tests/plugin_installation_smoke.php

更完整的开发约定与运维验收步骤见开发文档和运维文档。

文档与机器可读资源

官网同时提供面向用户、开发者、搜索引擎和 AI 的资料：

资源	地址
官网首页	shopagg.org
使用文档	shopagg.org/usage
开发文档	shopagg.org/developer
产品能力清单	shopagg.org/capabilities
版本发布	shopagg.org/releases
AI 项目摘要	llms.txt
AI 完整上下文	llms-full.txt
项目信息 JSON	api/project.json
产品能力 JSON	api/capabilities.json
文档索引 JSON	api/docs/index.json
最新版本 JSON	api/releases/latest.json
静态 API OpenAPI	api/openapi.json

版本与更新

稳定版本通过 GitHub Release 发布，后台可以检查新版本、下载更新包，并在覆盖文件前创建备份。发布历史、下载地址和版本说明统一展示在官网版本页。

生产环境升级前请先阅读程序更新、备份与故障恢复，并备份 storage/site.db、uploads/ 和自定义主题。

参与贡献

欢迎提交 Issue 和 Pull Request：

1. Fork 本仓库并从最新代码创建分支。
2. 保持改动聚焦，并补充必要的验证。
3. 提交 Pull Request，说明问题、行为变化和验证方式。

准备贡献前建议阅读开发文档，了解核心架构、插件边界、主题规范和安全要求。

License

MIT License — 可自由用于个人和商业项目，也可以修改与分发。

---