ShopX 电商系统安装部署说明书

## 关于本手册

本文档面向系统运维人员，说明 ShopX 电商系统的安装、配置和生产部署流程。适用于已获得编译后可执行文件（`shopx`），无需自行编译的场景。

---

## 目录

- [第一章 环境要求](#第一章-环境要求)
- [第二章 快速安装](#第二章-快速安装)
- [第三章 系统安装](#第三章-系统安装)
- [第四章 配置文件说明](#第四章-配置文件说明)
- [第五章 部署运行](#第五章-部署运行)
- [第六章 系统初始化](#第六章-系统初始化)
- [第七章 升级维护](#第七章-升级维护)
- [附录](#附录)

---

## 第一章 环境要求

### 1.1 硬件要求

| 配置项 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | 1 核 | 2 核及以上 |
| 内存 | 1 GB | 4 GB 及以上 |
| 磁盘 | 10 GB 可用空间 | 50 GB 及以上（视商品图片量而定） |
| 网络 | 公网 IP | 固定公网 IP 或域名 |

### 1.2 软件要求

| 软件 | 版本要求 | 说明 |
|---|---|---|
| 操作系统 | Linux（推荐 Ubuntu 20.04+ / CentOS 8+ / Debian 11+） | 也支持 Windows Server / macOS |
| MySQL | 8.0+ | 生产环境必需 |
| Nginx | 1.20+ | 生产环境反向代理推荐 |

### 1.3 依赖服务

| 服务 | 用途 | 是否必须 |
|---|---|---|
| Redis | Session 存储、缓存 | 可选（默认使用文件存储 Session） |

### 1.4 端口规划

| 端口 | 用途 | 说明 |
|---|---|---|
| 9999（默认） | Web 服务端口 | 启动时通过 `-p` 参数修改 |
| 3306 | MySQL 数据库 | 按实际数据库地址配置 |
| 6379 | Redis | 使用 Redis Session 引擎时需要 |

---

## 第二章 快速安装

### 2.1 使用预编译包安装

从发布渠道获取对应操作系统和架构的压缩包，解压到目标目录：

```bash
mkdir -p /opt/shopx
cd /opt/shopx
tar -zxvf shopx_linux_amd64.tar.gz
```

### 2.2 目录结构说明

安装后的目录结构如下：

```
/opt/shopx/
├── shopx                        # 主程序可执行文件
├── config/
│   ├── config.yaml.sample      # 配置文件模板
│   ├── install.shopx.sql       # 数据库安装脚本（全量建表）
│   ├── insert.*.sql            # 初始化数据脚本（商家、导航、广告、地区等）
│   ├── preupgrade.*.sql        # 数据库升级前置脚本
│   ├── ua.txt                  # User-Agent 解析库
│   └── vhosts/                 # 虚拟主机配置目录
├── data/
│   ├── cache/                  # 缓存目录（SSL 证书缓存等）
│   ├── logs/                   # 运行日志目录
│   ├── ip2region/              # IP 地理信息库
│   ├── product/                # 商品相关数据
│   ├── sego/                   # 中文分词库
│   └── temp/                   # 临时文件
├── public/
│   └── upload/                 # 上传文件目录（运行时创建）
└── license.key                 # 授权文件（如有）
```

模板和大部分静态资源已编译进可执行文件，部署时无需额外复制模板目录。

---

## 第三章 系统安装

本章介绍首次运行时的安装步骤。安装通过 Web 可视化界面完成，无需手动操作数据库。

### 3.1 启动程序

```bash
cd /opt/shopx
./shopx
```

> **提示**：Linux 系统下，首次执行前请先赋予可执行权限：`chmod +x ./shopx`

启动后终端将持续输出日志。如需后台运行：

```bash
nohup ./shopx &
```

### 3.2 进入安装页面

打开浏览器，访问以下地址：

```
http://服务器IP:9999/admin/setup
```

系统自动进入安装引导页面。

### 3.3 配置数据库和管理员信息

在安装页面中填写以下信息：

| 配置项 | 说明 | 默认值 | 示例 |
|---|---|---|---|
| 数据库类型 | MySQL | `MySQL` | MySQL |
| 数据库主机 | 数据库服务器地址和端口 | `127.0.0.1:3306` | `127.0.0.1:3306` |
| 数据库用户 | 数据库登录用户名 | `root` | `root` |
| 数据库密码 | 数据库登录密码 | — | `your_password` |
| 数据库名称 | 数据库名（需提前创建或由安装程序创建） | `shopx` | `shopx` |
| 数据表字符集 | 表字符集 | `utf8mb4` | `utf8mb4` |
| 管理员用户名 | 系统超级管理员账号 | `admin` | `admin` |
| 管理员密码 | 登录密码（不少于 8 位） | — | `admin123` |
| 管理员邮箱 | 管理员电子邮箱 | — | `admin@example.com` |

填写完成后点击提交，系统自动完成以下操作：

- 创建数据表结构（执行 `install.shopx.sql`）
- 导入初始化数据（商家、店铺、导航、广告位、售后原因、地区数据等）
- 创建管理员账号
- 生成配置文件 `config/config.yaml`

> **说明**：地区数据量较大，导入过程可能需要一些时间，请耐心等待页面响应。

### 3.4 使用命令行静默安装（可选）

如环境不支持浏览器访问，可使用命令行完成安装：

```bash
./shopx init \
  --user=root \
  --password="your_password" \
  --host="127.0.0.1:3306" \
  --database=shopx \
  --adminUser=admin \
  --adminPass="admin123" \
  --adminEmail="admin@example.com"
```

**`init` 命令参数说明：**

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--user` | 数据库用户名 | `root` |
| `--password` | 数据库密码 | — |
| `--host` | 数据库服务器地址 | `127.0.0.1:3306` |
| `--database` | 数据库名称 | `shopx` |
| `--type` | 数据库类型 | `mysql` |
| `--charset` | 数据表字符集 | `utf8mb4` |
| `--adminUser` | 管理员用户名 | `admin` |
| `--adminPass` | 管理员密码（不少于 8 位） | — |
| `--adminEmail` | 管理员邮箱 | — |
| `--adminPwdRandom` | 是否随机生成管理员密码 | `false`（设为 `true` 时自动生成并写入 `nging-password.txt`） |

执行成功后，终端输出安装成功提示。之后启动程序即可登录：

```bash
./shopx
```

---

## 第四章 配置文件说明

### 4.1 配置文件路径

配置文件位于 `config/config.yaml`。首次安装时会自动从模板复制：

```bash
config/config.yaml.sample
```

### 4.2 配置项详解

#### 4.2.1 数据库配置

```yaml
db {
  type : "mysql"                  # 数据库类型（仅支持 mysql）
  user : "root"                   # 数据库用户名
  password : "root"               # 数据库密码
  host : "127.0.0.1:3306"         # 数据库地址和端口
  database : "shopx"              # 数据库名称
  debug : true                    # 是否打印 SQL 日志（生产环境建议设为 false）
  connMaxLifetime : ""            # 连接最大生存时间
  maxIdleConns : 0                # 最大空闲连接数（0 使用默认值）
  maxOpenConns : 0                # 最大打开连接数（0 使用默认值）
}
```

#### 4.2.2 系统配置

```yaml
sys {
  env : "dev"                     # 运行环境：dev / prod
  sessionName : "WEBXSID"         # Session 名称
  sessionEngine : "file"          # Session 存储引擎：cookie / file / redis
  sessionConfig : {
    # file 引擎配置
    "savePath" : ""
    # redis 引擎配置
    "maxIdle"  : 10
    "network"  : "tcp"
    "address"  : "127.0.0.1:6379"
    "password" : ""
    "db"       : 5
  }
  realIPProxyType : "cloudflare"  # 代理类型：cloudflare / X-Forwarded-For 等
}
```

#### 4.2.3 Cookie 配置

```yaml
cookie {
  path     : "/"                  # Cookie 路径
  domain   : ""                   # Cookie 域名
  maxAge   : 0                    # 过期时间（0 为关闭浏览器即失效）
  httpOnly : true                 # 禁止 JavaScript 读取
  hashKey  : "2cf44258065525c376137197bc597f36"  # 32 位哈希密钥
  blockKey : "7ddcb30acc09b4518b2309e715d9157a"  # 32 位加密密钥
}
```

> **安全提示**：生产环境请务必修改 `hashKey` 和 `blockKey` 为随机字符串。

#### 4.2.4 多语言配置

```yaml
language {
  Default      : "zh-CN"          # 默认语言
  Fallback     : ""               # 回退语言
  AllList      : ["zh-CN","en"]   # 可用语言列表
  RulesPath    : ["./config/i18n/rules"]    # 语言规则目录
  MessagesPath : ["./config/i18n/messages"] # 语言包目录
  Reload       : true             # 是否允许热重载
  Extra : {
    "zh-CN" : { label : "简体中文", flag : "🇨🇳" }
    "en"    : { label : "English", flag : "🇺🇸" }
  }
}
```

#### 4.2.5 扩展功能配置

**监控指标**：
```yaml
extend {
  metrics : {
    enable : true
    user : user
    password : pass
  }
}
```

**OAuth2 后台登录**：
```yaml
  oauth2backend : {
    on : true
    accounts : [
      {
        on     : true
        name   : "nging"
        appID  : "应用 ID"
        secret : "应用密钥"
        extra  : {
          hostURL : "http://127.0.0.1:28081"
          title   : ""
        }
      }
    ]
  }
```

**翻译服务**：
```yaml
  translate : {
    providers : [
      {
        provider  : "libre"
        config : {
          appid  : ""
          secret : ""
          endpoint : "http://127.0.0.1:5000/translate"
        }
      }
    ]
    on : true
    allowForceTranslate : true
  }
```

### 4.3 功能门控

系统通过功能门控（Feature Flag）控制模块显示。在后台系统设置中配置以下开关：

| 门控标识 | 功能 | 说明 |
|---|---|---|
| `shopx-multi-store` | 多店铺模式 | 开启后支持多商家多店铺管理 |
| `shopx-after-sale-service` | 售后服务 | 开启后在订单和店铺管理中显示售后功能 |
| `shopx-goods-custom` | 商品定制 | 开启后在平台配置中显示定制方案管理 |

---

## 第五章 部署运行

### 5.1 Linux 服务器部署

#### 5.1.1 部署步骤

```bash
# 创建部署目录
mkdir -p /opt/shopx
cd /opt/shopx

# 解压构建产物
tar -zxvf shopx_linux_amd64.tar.gz
```

#### 5.1.2 启动服务

```bash
# 前台启动（测试用）
./shopx

# 后台启动
nohup ./shopx &
```

#### 5.1.3 命令行参数

| 短参数 | 长参数 | 说明 | 默认值 |
|---|---|---|---|
| `-p` | `--port` | 监听端口 | `9999` |
| `-a` | `--address` | 监听地址 | `0.0.0.0` |
| `-c` | `--config` | 配置文件路径 | `config/config.yaml` |
| `-d` | `--dftconfig` | 默认配置目录 | `config` |
| `-f` | `--frontend.domain` | 前端域名 | — |
| `-b` | `--backend.domain` | 后台域名 | — |
| `-t` | `--type` | 运行类型 | `manager` |
| `-s` | `--startup` | 启动时附带的服务 | `task` |

示例：

```bash
# 指定端口和监听地址
./shopx -p 9998 -a 0.0.0.0

# 前后端分离域名
./shopx -f www.mystore.com -b admin.mystore.com:9999
```

#### 5.1.4 使用 systemd 管理（推荐）

创建 systemd 服务文件 `/etc/systemd/system/shopx.service`：

```ini
[Unit]
Description=ShopX E-commerce System
After=network.target mysql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/shopx
ExecStart=/opt/shopx/shopx
Restart=always
RestartSec=5
StandardOutput=syslog
StandardError=syslog

[Install]
WantedBy=multi-user.target
```

启用服务：

```bash
systemctl daemon-reload
systemctl enable shopx
systemctl start shopx
systemctl status shopx
```

#### 5.1.5 使用内置服务管理命令

系统支持通过命令行安装/卸载系统服务：

```bash
# 安装为系统服务
./shopx service install

# 启动服务
./shopx service start

# 停止服务
./shopx service stop

# 重启服务
./shopx service restart

# 卸载服务
./shopx service uninstall
```

### 5.2 Nginx 反向代理配置

#### 5.2.1 配置文件

创建 `/etc/nginx/sites-available/shopx.conf`：

```nginx
upstream shopx_backend {
    server 127.0.0.1:9999;
    keepalive 64;
}

server {
    listen 80;
    server_name your-domain.com;

# 强制 HTTPS 跳转（推荐）
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

ssl_certificate     /etc/nginx/ssl/your-domain.com.pem;
    ssl_certificate_key /etc/nginx/ssl/your-domain.com.key;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

# 上传文件大小限制
    client_max_body_size 50M;

# 后台管理
    location / {
        proxy_pass http://shopx_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
}
```

#### 5.2.2 上传文件独立目录（可选）

```nginx
location /public/upload/ {
    alias /opt/shopx/public/upload/;
    expires 30d;
    add_header Cache-Control "public, immutable";
}
```

### 5.3 目录权限

```bash
# 设置数据和日志目录可写
chmod -R 755 /opt/shopx/data
chmod -R 755 /opt/shopx/data/logs
chmod -R 755 /opt/shopx/data/cache
chmod -R 755 /opt/shopx/data/temp
chmod -R 755 /opt/shopx/data/product

# 如果使用文件上传
chmod -R 755 /opt/shopx/public/upload
```

### 5.4 安全设置

1. **修改密钥**：修改 `config.yaml` 中的 `cookie.hashKey` 和 `cookie.blockKey` 为随机 32 位字符串
2. **防火墙**：仅对外开放 Web 端口（80/443），数据库端口仅允许内网访问
3. **HTTPS**：生产环境务必配置 SSL 证书
4. **Session 配置**：高安全场景下建议使用 Redis 存储 Session
5. **配置文件保护**：确保 `config/config.yaml` 不通过 Web 直接访问

---

## 第六章 系统初始化

### 6.1 首次访问

安装完成后，启动程序：

```bash
./shopx
```

服务启动后，通过浏览器访问：

```
http://服务器IP:9999/
```

### 6.2 管理员登录

使用安装时设置的管理员账号和密码登录。

| 账号 | 密码 | 说明 |
|---|---|---|
| （安装时设置） | （安装时设置） | 超级管理员 |

> **安全提醒**：如安装时使用了弱密码，请立即登录后修改。

### 6.3 登录后配置流程

1. **修改管理员密码**：进入 账号安全 → 修改密码
2. **配置站点信息**：设置 → 系统设置 → 系统设置 → 站点信息，填写网站名称、SEO 信息等
3. **配置支付方式**：设置 → 系统设置 → 在线支付 → 支付接口设置，配置支付宝/微信支付等
4. **配置快递查询**：设置 → 系统设置 → 商城配置 → 物流查询接口，配置物流查询接口账号
5. **配置汇率接口**：设置 → 系统设置 → 第三方接口 → 汇率接口，配置汇率接口 API Key
6. **配置翻译接口**：设置 → 系统设置 → 第三方接口 → 翻译
7. **添加商品分类**：平台配置 → 商品分类，建立商品分类体系

---

## 第七章 升级维护

### 7.1 升级流程

```bash
# 1. 备份当前程序和数据
cp /opt/shopx/shopx /opt/shopx/shopx.bak
mysqldump -u root -p shopx > /opt/shopx/backup/shopx_$(date +%Y%m%d).sql

# 2. 停止服务
systemctl stop shopx

# 3. 备份配置文件
cp /opt/shopx/config/config.yaml /opt/shopx/config/config.yaml.bak

# 4. 解压新版程序
cd /opt/shopx
unzip -o shopx_linux_amd64.zip

# 5. 恢复配置文件
cp /opt/shopx/config/config.yaml.bak /opt/shopx/config/config.yaml

# 6. 启动服务
systemctl start shopx
```

### 7.2 数据库升级

如果新版包含数据库变更，升级日志文件位于 `config/` 目录下：

```bash
# 查看升级日志
ls config/upgrade_*.log.html

# 按需执行升级 SQL
mysql -u root -p shopx < config/upgrade_版本号.sql
```

### 7.3 日志管理

日志文件位于 `data/logs/` 目录，按天滚动。

```bash
# 查看日志文件
ls -lh /opt/shopx/data/logs/

# 日志切割示例（使用 logrotate）
# 创建 /etc/logrotate.d/shopx
/opt/shopx/data/logs/*.log {
    daily
    rotate 30
    compress
    missingok
    notifempty
    copytruncate
}
```

### 7.4 备份策略

| 数据 | 备份方式 | 频率 |
|---|---|---|
| 数据库 | `mysqldump` | 每日 |
| 配置文件 | 直接复制 | 每次修改后 |
| 上传文件 | `rsync` | 每周 |
| 程序文件 | `tar` 归档 | 每次升级前 |

---

## 附录

### A. 环境检查清单

```bash
# 检查操作系统版本
cat /etc/os-release

# 检查 MySQL 版本
mysql --version

# 检查 Nginx 版本
nginx -v

# 检查磁盘空间
df -h

# 检查内存
free -m
```

### B. 启动故障排查

| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 启动报错&#34;数据库连接失败&#34; | 数据库配置错误或未启动 | 检查 `config.yaml` 中数据库配置；检查 MySQL 服务状态 |
| 启动后端口未监听 | 端口被占用 | `lsof -i:9999` 查看端口占用 |
| 页面 404 | 资源文件未正确编译 | 确认使用的可执行文件包含嵌入资源（使用 bindata 版本） |
| 登录失败 | 未完成安装 | 确认已访问 `/admin/setup` 完成安装引导 |
| Session 错误 | Session 存储配置问题 | 检查 `sessionEngine` 配置是否正确 |

### C. 数据备份脚本参考

```bash
#!/bin/bash
# 备份脚本 /opt/shopx/backup.sh

BACKUP_DIR=/opt/shopx/backup
DATE=$(date +%Y%m%d_%H%M%S)
DB_NAME=shopx
DB_USER=root
DB_PASS=your_password

mkdir -p $BACKUP_DIR

# 备份数据库
mysqldump -u$DB_USER -p$DB_PASS $DB_NAME | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# 备份配置文件
cp /opt/shopx/config/config.yaml $BACKUP_DIR/config_$DATE.yaml

# 保留最近 30 天备份
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +30 -delete
find $BACKUP_DIR -name "config_*.yaml" -mtime +30 -delete

echo "Backup completed: $DATE"
```

### D. 相关资源

| 资源 | 地址 |
|---|---|
| 底层框架 WebCore | `github.com/coscms/webcore` |
| 前端框架 Webx | `github.com/admpub/webx` |
| 后台框架 Nging | `github.com/admpub/nging/v5` |

ShopX 电商系统安装部署说明书

Shopx商城系统

Share this article

Comments (0)

To comment

ShopX 电商系统 安装部署说明书

Shopx商城系统

Share this article

Comments (0)

To comment

To comment

ShopX 电商系统安装部署说明书