SHOPAGG 使用文档

角色与阅读路线

不同岗位关注点不同，可以按下面路线阅读：

安装部署

SHOPAGG 的部署设计接近传统 PHP 虚拟主机体验，不需要 Composer、Node.js 或前端构建工具。准备好 PHP 和 SQLite 扩展后，上传源码并访问站点即可触发初始化。

运行环境要求

三种部署方式

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

wget https://github.com/zhpelo/shopagg-b2b-website/archive/refs/heads/main.zip
unzip main.zip
mv shopagg-b2b-website-main shopagg-b2b-website
chmod -R 755 shopagg-b2b-website/storage shopagg-b2b-website/uploads

打开 https://www.shopagg.com/dashboard/b2b-sites/create
按页面提示填写站点信息
无需配置服务器、上传代码或手动初始化数据库

Apache 配置要点

源码内置 .htaccess，常规 Apache 环境只需要确保站点目录允许重写：

AllowOverride All
Options FollowSymLinks

部署完成后访问首页。如果系统发现数据库不存在，会自动创建 storage/site.db，执行迁移并写入默认数据。

Nginx 配置要点

Nginx 环境需要把不存在的路径转发到 index.php：

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

location ~ ^/(storage|app|Documents)/ {
    deny all;
}

首次登录与初始化

首次安装后访问 /admin/login。登录成功后先不要急着录入大量内容，建议按下面顺序完成基础配置。

初始化检查清单

• 确认后台右下角或更新页显示版本为 v1.2.3。
• 确认 storage/ 和 uploads/ 可写。
• 确认当前主题已启用，前台首页能正常打开。
• 确认默认货币代码，例如 USD、EUR、CNY。
• 确认 Google Translate 翻译入口是否按业务需要显示。
• 确认后台员工账号只有必要权限。

后台导航说明

后台菜单按日常运营流程组织。管理员可以看到全部模块，员工账号看到的菜单取决于授权。

仪表盘怎么用

仪表盘适合每天登录后快速判断站点状态：

• 产品总数、已发布产品数量。
• 文章、案例、页面数量。
• 新留言和新询盘数量。
• 最近提交的客户信息。
• 安全检查提示，例如数据库文件权限、敏感目录访问规则。
• 程序更新、迁移和备份状态入口。

如果你看到询盘或留言数量异常增长，应优先检查来源 IP、表单内容和是否存在垃圾提交。

产品中心

产品中心是 B2B 官网的核心模块。一个可销售、可被搜索、可被询盘的产品通常需要完整标题、分类、图片、详情、价格模式、SEO 和询盘入口。

新增产品

进入「产品中心 → 产品列表」，点击添加产品。建议按下面顺序填写：

1. 产品标题：使用客户会搜索的产品名称。
2. Slug：使用英文小写、数字和连字符。
3. 产品分类：确保产品进入正确分类，方便筛选和导航。
4. 摘要：用于列表页和详情页开头，控制在两三句话内。
5. 产品描述：写清规格、材料、用途、包装、认证、交期等信息。
6. 图片：至少上传主图，重要产品建议添加多张细节图。
7. 价格模式：选择阶梯价格、SKU 价格、价格区间或面谈价格。
8. SEO：填写 SEO 标题、关键词、描述。
9. 状态：确认内容完整后再发布。

Slug 规则

Slug 用于生成前台网址，例如：

/product/stainless-steel-pipe
/product/industrial-ball-valve

系统会自动处理大小写和非法字符。推荐做法：

• 使用简短英文。
• 单词之间用 -。
• 不要频繁修改已经被搜索引擎收录的 Slug。
• 不要把日期、内部编号或临时促销词写进核心产品 Slug。

产品分类

产品分类影响前台筛选、导航和 SEO。建议先建立一级和二级分类，再录入产品。

不要把过多产品堆在一个分类里，也不要为每个单品创建单独分类。

价格模式

v1.2.3 的产品价格支持四种展示方式，前台统一读取系统设置里的全局货币。

产品发布建议

• 重点产品至少准备 5 张图片：主图、细节图、应用场景、包装、资质或工厂图。
• 详情页不要只放参数表，应补充采购关心的问题：MOQ、交期、定制范围、样品政策。
• 如果产品可定制，使用面谈价格并在详情中写清可定制项。
• 如果价格稳定，优先使用阶梯价格或 SKU 价格，减少销售重复沟通成本。
• 每次大批量更新后，从前台打开产品列表和详情页确认图片、价格、询盘按钮都正常。

内容管理

内容管理包含文章、案例、页面和媒体库。它们共同支撑网站可信度、SEO 和客户转化。

文章管理

文章适合发布：

• 行业资讯。
• 产品采购指南。
• 展会新闻。
• 常见问题解答。
• 公司动态。

文章建议保持持续更新。标题应该贴近客户搜索词，正文中自然补充产品链接和相关案例，不要堆砌关键词。

案例管理

案例适合展示交付能力：

• 客户行业和地区。
• 项目背景。
• 使用的产品或解决方案。
• 交付周期、包装、运输方式。
• 结果和客户反馈。

案例不一定透露客户名称，但要提供足够真实的应用场景，让潜在客户判断你是否有类似经验。

页面管理

页面适合放固定内容：

• 关于我们。
• 联系我们。
• 服务能力。
• 质量控制。
• FAQ。
• 隐私政策。

页面通常会通过菜单加入顶部导航或页脚导航。发布页面后记得进入「外观区块 → 菜单管理」添加入口。

媒体库

媒体库用于集中管理图片、视频和附件。

建议：

• 用文件夹区分产品图、公司图、证书、博客图和案例图。
• 上传前压缩超大图片，避免前台加载过慢。
• 图片文件名使用英文，例如 factory-workshop.webp。
• 删除媒体前确认没有被产品、页面、区块或轮播引用。

收件箱与询盘

收件箱分为联系留言和产品询单。联系留言通常来自联系页；产品询单通常来自产品详情页，包含更明确的采购上下文。

联系留言

联系留言常见字段：

• 姓名。
• 邮箱。
• 电话。
• 公司。
• 国家或地区。
• 留言内容。
• 提交时间和来源 IP。

处理建议：

1. 先判断是否垃圾信息。
2. 对有效留言标记跟进状态。
3. 将重要客户同步到 CRM、表格或内部销售系统。
4. 回复前确认客户时区和语种。

产品询单

产品询单通常包含：

• 目标产品。
• 采购数量。
• 客户联系方式。
• 公司名称。
• 留言说明。
• 来源产品详情页。

销售跟进时建议先打开对应产品，确认当前价格模式、MOQ、图片和规格说明，再回复客户。对于面谈价格产品，应尽快补充关键问题，例如材质、尺寸、数量、包装和目的港。

询盘状态建议

外观区块

外观区块决定前台展示。管理员可以在后台更换主题、编辑模板区块、维护菜单和轮播图。

网站模版

进入「外观区块 → 网站模版」后，系统会读取 /themes 目录下的主题。

可执行操作：

• 查看已安装主题。
• 查看主题封面图。
• 上传 zip 主题包。
• 启用指定主题。

主题上传包必须满足：

• 压缩包里只能有一套主题。
• 主题根目录必须包含 style.css。
• style.css 顶部必须包含主题元数据，至少包含 Theme Name。
• 不应包含破坏性脚本或覆盖用户数据的逻辑。

模板区块

模板区块让运营人员不用改代码也能换文字、图片、按钮、产品和展示数量。

常见字段：

保存区块后如果前台没有变化，优先检查：

1. 当前启用主题是否正确。
2. 修改的区块是否属于当前主题。
3. 前台页面是否缓存。
4. 区块字段是否被模板实际读取。

菜单管理

菜单支持多个菜单、多级菜单和拖拽排序。常见 Slug：

菜单项可以链接到页面、分类、产品、文章或自定义 URL。上线前务必逐个点击检查链接是否有效。

轮播图

轮播图适合维护首页首屏、活动 Banner 或页面顶部视觉区域。

每组轮播通常包含：

• 轮播图名称。
• Slug。
• 多张图片。
• 标题。
• 描述。
• 按钮文字和链接。
• 排序和状态。

建议所有轮播图片保持同一比例，避免前台切换时页面跳动。

系统设置

系统设置包含全站基础配置、公司信息、翻译、自定义代码和程序更新。

翻译设置

SHOPAGG 的多语言能力基于 Google Translate 在线翻译功能实现。后台可配置前台翻译入口和语言选项。

使用建议：

• 根据目标市场选择常用语言，不必一次展示全部语种。
• 如果面向欧美市场，优先配置英语、西班牙语、法语、德语、意大利语、葡萄牙语。
• 如果面向中东和东南亚市场，补充阿拉伯语、土耳其语、越南语、泰语、印尼语等。
• 翻译依赖 Google 在线服务，客户网络环境可能影响加载速度。

自定义代码

自定义代码适合添加：

• Google Analytics。
• Search Console 验证。
• 第三方客服插件。
• 广告转化跟踪。
• 站点统计脚本。

不要在自定义代码里粘贴来源不明的脚本。任何会读取表单、重定向页面、弹出登录框或加载远程可执行代码的脚本，都应先经过技术人员审核。

程序更新与备份

程序更新页通常用于：

• 查看当前版本。
• 检查远程版本。
• 安装更新包。
• 查看数据库迁移状态。
• 手动执行待处理迁移。
• 查看备份和更新日志。

更新前建议：

1. 备份 storage/site.db。
2. 备份 uploads/。
3. 确认当前主题是否有自定义修改。
4. 在低峰时间执行更新。
5. 更新后检查首页、产品详情、后台登录、询盘提交和媒体上传。

员工与权限

员工管理用于创建非管理员账号，并按职责分配模块权限。

角色区别

权限建议

遵循“够用即可”的原则。不要为了省事把所有员工都设置为管理员。

日常操作流程

建议每天或每周按固定流程检查站点：

1. 登录后台查看仪表盘。
2. 处理新留言和新询盘。
3. 更新产品、文章或案例。
4. 整理媒体库新增图片。
5. 检查首页区块、菜单和轮播是否需要调整。
6. 查看程序更新和迁移状态。
7. 定期下载数据库和上传文件备份。

上线前检查清单

常见问题

为什么上传主题后不能启用？

常见原因：

• zip 包里包含多个主题目录。
• 主题根目录缺少 style.css。
• style.css 没有主题元数据。
• 压缩包结构多套了一层无关目录。
• 上传包被服务器大小限制拦截。

为什么主题没有封面图？

后台优先读取主题目录里的 screenshot.jpg。如果主题没有这个文件，主题列表会显示无预览图，但不一定影响启用。

为什么产品别名会被自动改成小写？

Slug 用于 URL，系统会统一过滤和标准化，避免中文、空格、特殊符号导致链接不稳定。

当前支持多少种翻译语言？

当前多语言功能基于 Google Translate 在线翻译能力实现，后台语言目录支持 249 种语言。官网、后台和文档都应以 249 种语言作为统一口径。

为什么保存模板区块后前台没变化？

先确认当前启用主题，再确认修改的是当前主题对应区块。如果仍然无效，检查主题模板是否调用了该区块字段。

更新失败后怎么办？

不要重复点击更新。先查看更新日志和备份文件，确认数据库是否完整，再恢复备份或交给维护人员处理。