Updated: 2026-07-26
This guide explains how to upgrade Dujiao-Next from an older version to a newer version.
v1.4.0 embeds the storefront and admin panel frontends into the backend binary, changing the deployment shape from "three separate services" to "one process". This is a one-time deployment restructuring. Your data is fully compatible, but the deployment setup needs adjusting.
| v1.3.x and earlier | v1.4.0 onward | |
|---|---|---|
| Deployment units | api + user + admin (three services) | one process |
| Docker images | dujiaonext/api, dujiaonext/user, dujiaonext/admin | only dujiaonext/dujiao-next (the old dujiaonext/api is still pushed as a transitional alias) |
| Container count | 4-5 | 2-3 |
| Release artifacts | dujiao-next_*.tar.gz (API only) + dujiao-all_*.tar.gz (with frontends) | only dujiao-next_*.tar.gz |
| Binary name | dujiao-api / dujiao-server | dujiao-next |
| Domains | one each for storefront and admin | one |
| Admin entry | / on a dedicated domain | web.admin_path on the same site |
| Nginx | separate proxy rules for /api, /uploads, /sitemap.xml, /robots.txt | a single site-wide location / |
| Source repositories | dujiao-next, user, admin | frontends merged into dujiao-next under frontend/ |
There are no breaking changes at the data layer: the database, uploads/, and config.yml all carry over as-is.
Back up (see section 1 below).
Stop the old services:
docker compose -f <your compose file> downEdit your compose file: delete the user and admin services, keeping only redis (+ postgres) and dujiao-next. See Docker Compose Deployment for a complete example.
Add a web section to config.yml with a hard-to-guess admin path:
web:
admin_path: "/dj-mgmt-7x9k2"Set TAG=v1.4.0 in .env and remove the now-unused USER_PORT / ADMIN_PORT.
Start and verify:
docker compose --env-file .env -f <your compose file> pull
docker compose --env-file .env -f <your compose file> up -d
docker compose logs -f dujiao-nextSeeing Embedded SPAs: admin (/dj-mgmt-7x9k2), user (/) in the log means it worked.
Update Nginx: merge the two server blocks into one that forwards the whole site to the application port. The admin domain can be retired, or kept pointing at the same service.
dujiao-next_*.tar.gz.db/, uploads/, and config.yml into the new working directory.web.admin_path to config.yml.ExecStart in your systemd unit (the binary is now dujiao-next instead of dujiao-api / dujiao-server), then run systemctl daemon-reload.Embedded SPAs appears in the log.root directives that served user/dist and admin/dist can be removed.https://admin.example.com/ to https://shop.example.com/<web.admin_path>. Tell your administrators and update bookmarks.web.admin_path requires a process restart to take effect.dujiaonext/user and dujiaonext/admin images are no longer updated and can be pruned from your server.You must back up the following before upgrading:
config.yml)uploads/)See the Backup & Restore guide.
Always read the GitHub release notes for your target version before upgrading to understand:
When an upgrade introduces strict callback amount/currency validation or changes DujiaoPay configuration:
provider_type=dujiaopay. Prefer to let them complete or expire before upgrading.fiat_currency matches the currency stored on those payment records. Do not change that channel's fiat currency until the in-flight records are cleared.readonly_auditor, operations, support, integration, finance, and system_admin) for post-upgrade authorization smoke tests.The new version can adopt the signed webhook currency in a limited compatibility path when the signature, channel, provider order ID, merchant order ID, and amount all match and the old payment has no new-version fiat snapshot. This pre-upgrade check still avoids relying on that compatibility path. A currency mismatch on a payment that already has a new-version snapshot remains rejected. If this has already happened, retain the original callback and payment record for manual reconciliation; do not bypass amount or currency validation manually.
systemctl stop dujiaocp db/dujiao.db db/dujiao.db.bak.$(date +%Y%m%d)
cp config.yml config.yml.bak
cp -r uploads uploads.bakwget https://github.com/dujiao-next/dujiao-next/releases/download/vX.Y.Z/dujiao-next_vX.Y.Z_Linux_x86_64.tar.gz
tar -xzf dujiao-next_*.tar.gz dujiao-nextThe frontends update along with the binary — no separate static files to replace.
Compare against config.yml.example and add any new configuration options you need.
systemctl start dujiaoDatabase schema changes are migrated automatically by GORM at startup — no manual SQL required.
git pull origin main
# One-command build (includes the frontends)
goreleaser build --snapshot --single-target --cleanOr build manually — see Manual Deployment.
docker compose exec dujiao-next cp /app/db/dujiao.db /app/db/dujiao.db.bak
docker compose cp dujiao-next:/app/config.yml ./config.yml.bak# Set TAG in .env to the target version
docker compose --env-file .env -f <your compose file> pulldocker compose --env-file .env -f <your compose file> up -ddocker compose logs -f dujiao-nextVerify in this order:
/<web.admin_path> and confirm you can log inIf something goes wrong after upgrading:
systemctl stop dujiao
# Restore the database and configuration
cp db/dujiao.db.bak.YYYYMMDD db/dujiao.db
cp config.yml.bak config.yml
# Put the old binary back
systemctl start dujiaoRolling back from v1.4.0 to v1.3.x also requires redeploying the user / admin frontends and restoring the old Nginx configuration.
docker compose down
# Set TAG in .env back to the previous version and restore the database backup
docker compose --env-file .env -f <your compose file> up -d