EasyCard 易卡数字平台

主题

安装部署 ​

EasyCard 易卡数字平台采用单二进制部署，程序名为 cardgo（Windows 为 cardgo.exe）。兼容发行文件名继续使用 EasyCard-*。请只从下载中心或官方 GitHub Releases取得安装包。

1. 选择平台并校验 ​

操作系统架构归档
Windowsx64 / ARM64.zip
Linuxx64 / ARM64.tar.gz
macOSIntel / Apple Silicon.tar.gz

下载对应归档和同一版本的 SHA256SUMS，解压前验证：

powershell
# Windows PowerShell
Get-FileHash .\EasyCard-1.1.0-rc.3-windows-amd64.zip -Algorithm SHA256
bash
# Linux / macOS
sha256sum -c SHA256SUMS --ignore-missing
# macOS 也可使用：shasum -a 256 <归档文件>

校验通过后，打开归档内的 manifest.json，核对 version、platform、binary_sha256 与实际环境。任何摘要或平台不一致都应停止安装。

macOS 候选包

当前 macOS Intel/Apple Silicon 包是未签名、未公证的交叉编译候选，只用于受控验收。普通商业分发前必须完成 Developer ID 签名、Apple 公证、Staple，并在对应架构真机完成首装、重启、备份恢复和升级回滚。不要把关闭 Gatekeeper 或人工移除隔离属性作为正常安装方式。

2. Windows ​

  1. 下载与 CPU 架构一致的 Windows 归档并完成 SHA-256 校验。
  2. 解压到独立目录，例如 D:\EasyCard\。
  3. 运行 cardgo.exe。终端会显示实际监听地址和首次安装地址。
  4. 默认端口为 18765；仅在尚未初始化且默认端口被占用时，程序会从 18766 起选择可用端口。以终端显示为准。
  5. 在安装完成前仅允许本机访问，不要把安装向导直接暴露到公网。

生产环境应使用 Windows 服务或可靠进程守护，并在 Caddy/Nginx/IIS 等反向代理后提供 HTTPS。

3. Linux systemd（推荐） ​

要求 root、curl 或 wget、tar，支持 x64 和 ARM64：

bash
curl -fsSLO https://raw.githubusercontent.com/ecard8/EasyCard/main/install.sh
sudo bash install.sh --dir /opt/easycard --port 18765 -y

不指定版本时，安装器会选择最近公开的 GitHub Release（包含预发布），然后识别架构、下载归档、核对 SHA-256 与 cardgo -version、创建最小权限用户和加固 systemd 单元、保留既有配置/数据，并轮询 /health/ready。升级后 30 秒内未就绪会恢复上一版本二进制。安装器同时创建 /usr/local/bin/easycard 管理命令。只有复现、回滚或受控验收才需要使用 --version 固定版本。

常用运维命令：

bash
easycard                    # 无参数打开单次操作菜单，执行后退出
sudo easycard status
sudo easycard start
sudo easycard stop
sudo easycard restart
sudo easycard update        # 最近公开版本
sudo easycard update 1.1.0-rc.3
easycard port               # 查看端口
sudo easycard port 9090     # 更换端口
sudo easycard logs 200
sudo easycard logs -f

兼容 easycard -start、easycard -stop、easycard -restart、easycard -update、easycard -port。easycard update 仍执行架构、SHA-256、候选身份、健康和失败回滚检查。easycard port 会检查占用、重启验证并在失败时恢复原配置；它只改变 listen，不会联动反向代理常用的 base_url。

4. Linux 手动安装 ​

bash
VER=1.1.0-rc.3
ARCH=amd64 # ARM64 使用 arm64
curl -fLO "https://github.com/ecard8/EasyCard/releases/download/v${VER}/EasyCard-${VER}-linux-${ARCH}.tar.gz"
curl -fLO "https://github.com/ecard8/EasyCard/releases/download/v${VER}/SHA256SUMS"
sha256sum -c SHA256SUMS --ignore-missing

sudo install -d -m 0750 /opt/easycard
sudo tar -xzf "EasyCard-${VER}-linux-${ARCH}.tar.gz" -C /opt/easycard
sudo chmod 0750 /opt/easycard/cardgo
cd /opt/easycard
./cardgo

不要长期用 root 运行服务。手动部署也应建立专用用户、严格文件权限、进程守护和优雅停止。

5. Docker Compose ​

Linux 归档内包含 Dockerfile、docker-compose.yml、.env 与入口脚本：

bash
tar -xzf EasyCard-1.1.0-rc.3-linux-amd64.tar.gz
docker compose build --pull
docker compose up -d
docker compose ps

发行 Compose 默认以非 root、只读根文件系统、最小 Linux 能力运行，整个运行数据根挂载到持久卷。重建容器后必须验证管理员登录、数据、上传和备份仍然存在。不要挂载 Docker Socket，也不要使用宿主网络规避网络配置。

6. 首次安装 ​

首次访问 /admin 固定分两步：

  1. 阅读软件许可/免责声明和店铺经营者责任声明，主动确认同意。
  2. 创建首位管理员，填写显示名称、唯一邮箱、强密码和监听端口。

首次安装不要求代理地址或令牌。初始化会创建演示分类和商品，便于开发/验收；正式运营前应删除或替换演示数据。完成后立即绑定 TOTP，并离线保存一次性恢复码。

7. 监听、域名与反向代理 ​

  • listen 可只写端口，例如 18765；只监听本机时写 127.0.0.1:18765。
  • listen 是本机绑定地址，base_url 是客户与第三方回调看到的公开 HTTPS 根地址，两者不能自动联动。
  • 反向代理场景在“系统设置 → 网络与代理”选择 direct、local_proxy 或 custom。自定义模式只填写真实代理 IP/CIDR，不能信任全网。
  • 生产环境使用公共 CA HTTPS，并确保回调地址无账号信息、查询参数或片段。

8. 升级与回滚 ​

v1.1.0-rc.3 客户端网页可使用至站点时区 2026-12-30，从 2026-12-31 00:00 起必须升级。期限到达后仍可进入管理后台或执行 sudo easycard update；API、健康检查和支付回调不会被客户端门禁拦截。

Linux 更新器使用 /health 确认进程已启动且数据库可访问；/health/ready 还包含备份、渠道和运行监控等运营状态。后者存在告警时更新器会保留已正常启动的新版本并提示检查运行监控，只有 /health 在 30 秒内仍不可用才回滚程序。

升级前完整备份运行数据根，并在隔离实例验证可恢复。跨数据库迁移的版本不能只回退二进制；如数据不兼容，应恢复升级前完整备份。

bash
sudo easycard update

升级后验证：

  • /health 与 /health/ready；
  • 管理端登录、TOTP、审计和运行监控；
  • 商品、购物车、订单、交付和售后；
  • 每个已启用支付/通知/对象存储/共享协议；
  • 本地备份、远端取回与隔离恢复。

9. 商用发布边界 ​

候选包和自动化通过不能替代真实环境证据。正式营业前仍需完成目标主机、防火墙、公共 HTTPS、真实支付和通知、对象存储、共享协议、浏览器/手机/读屏器、备份恢复以及运营合规验收。未验收的外部能力保持关闭。

相关 ​

EasyCard 易卡数字平台官方网站

Copyright © 2026 ecard8.com