企业官网建设流程全解析

Dujiao-Next 是一个开箱即用的数字商品电商平台（Go 后端 + Vue 3 双前端），支持数字礼品卡、AI 服务、社交账号等虚拟商品的销售与自动发货。本文带你用 Docker 快速部署 Dujiao-Next：只需要1 个镜像、1 条 docker run 命令，再配合一份 config.yml 配置文件即可完成上线，并逐段讲解配置项的含义与生产环境最佳实践。

项目概览：一个镜像里装了什么

与传统「前端容器 + Nginx + 后端容器」的三件套不同，Dujiao-Next 的 Docker 镜像是一个单个全栈镜像：

• 管理后台（admin SPA）与用户商城（user SPA）在构建期编译完成；
• 两份前端产物通过go:embed打进同一个 Go 二进制（见 embed_fullstack.go）；
• 同一个进程、同一个 8080 端口同时提供 API、商城页面和后台页面，无需 Nginx，无需独立前端容器；
• SQLite 数据库、上传目录、日志目录全部内置，首次启动自动创建。

这正是 Dockerfile 头部的注释所描述的设计目标（见 Dockerfile）。

单个全栈镜像是如何构建的

构建过程分为三个阶段（Dockerfile）：

带来的好处非常直接：部署 = 跑一个容器，升级 = 拉新镜像重启，故障面最小化。

部署准备：生成 3 把互不相同的密钥

在启动前，把 config.yml.example 复制为config.yml，并替换其中 3 个占位密钥：

cp config.yml.example config.yml # 执行 3 次，得到 3 个不同的强随机值 openssl rand -hex 32 openssl rand -hex 32 openssl rand -hex 32

分别填入以下 3 项（见 config.yml.example）：

⚠️关键约束：这 3 个密钥必须「足够长（≥32 字符）、彼此不同、且不是占位默认值」，否则服务会直接拒绝启动并打印以下运行时密钥过弱、重复或仍为默认值。该校验逻辑在 main.go。这是项目刻意的安全兜底——配置不达标，就宁可不启动。

最快启动方法：一条 docker run 命令

准备好config.yml后（记得把server.mode改为release），执行：

docker run -d --name dujiao-next \ -p 8080:8080 \ -v $PWD/config.yml:/app/config.yml:ro \ -v $PWD/db:/app/db \ -v $PWD/uploads:/app/uploads \ -v $PWD/logs:/app/logs \ dujiaonext/dujiao-next:latest

几个要点：

• -v $PWD/config.yml:/app/config.yml:ro：配置文件以只读方式挂入容器，对应镜像中预留的 config.yml.example 位置；
• -v $PWD/db:/app/db等三个数据卷：数据库、上传文件、日志都在宿主机落盘。不挂载的话，删容器即丢数据；
• 默认数据目录为 SQLite 文件./db/dujiao.db，小流量场景零运维即可运行。

启动后验证健康检查（router.go）：

curl http://localhost:8080/health # {"status":"ok"}

然后访问http://你的服务器:8080/打开商城首页，访问http://你的服务器:8080/admin进入后台（路径见下文web.admin_path说明）。

config.yml 配置项详解

完整默认值与注释见 config.yml.example，结构定义见 config.go。下面按重要程度挑出部署时真正需要关心的部分。

基础运行：app / server / log

app: secret_key: <openssl rand -hex 32 生成> totp_issuer: Dujiao-Next # 后台 2FA 验证器中显示的发行方名称 server: host: 0.0.0.0 port: 8080 mode: release # 生产环境务必用 release（默认 debug） trusted_proxies: # 只信任真实反向代理的网段 - 127.0.0.1/32 - ::1/128

🔒trusted_proxies是安全关键项：同机 Nginx 用默认值即可；Docker 或 CDN 部署必须改成真实代理网段，禁止配置0.0.0.0/0（见 config.yml.example 的注释）。配错会让登录限流的来源 IP 判断失真。

数据库与 Token：database / jwt

database: driver: sqlite # sqlite 或 postgres dsn: ./db/dujiao.db # postgres 时改为连接串 jwt: secret: <独立随机值> expire_hours: 24 # 后台 Token 有效期（小时） user_jwt: secret: <独立随机值> expire_hours: 24 remember_me_expire_hours: 168 # 用户「记住我」7 天

后台与用户 Token 采用互相隔离的双 realm 设计，两套密钥独立，任一泄露不影响另一方。

首次管理员初始化：bootstrap

bootstrap: default_admin_username: "admin" default_admin_password: "<强密码，仅首次启动生效>"

首次启动时自动创建默认管理员（见 main.go）。注意：

• 密码需满足security.password_policy策略，admin/admin123这类弱值在 release 模式下会直接拒绝启动；
• 环境变量DJ_DEFAULT_ADMIN_USERNAME/DJ_DEFAULT_ADMIN_PASSWORD优先级更高，方便 Docker 场景注入而不用写进文件；
• 留空则跳过初始化，管理员需在安装流程中另行创建。

后台访问路径：web.admin_path

web: admin_path: "/dj-mgmt-7x9k2" # 强烈建议改成不易猜测的字符串

• 默认是/admin，release 模式下保持默认会在启动日志中收到安全风险警告（见 main.go）；
• 该配置仅在 fullstack 镜像下生效——前端基础路径是启动时动态注入的，同一镜像可挂到任意前缀，这是「改后台路径无需重新构建镜像」的关键设计；
• /api、/uploads、/health为保留前缀，不能与之冲突。

可选组件：redis / queue

redis: enabled: true # 设为 false 即可让服务在完全无 Redis 时运行 host: 127.0.0.1 port: 6379 queue: enabled: true # asynq 异步任务（邮件、通知、库存同步等） host: 127.0.0.1 port: 6379 db: 1 concurrency: 10 upstream_sync_interval: "5m" # 上游库存同步间隔

Dujiao-Next 的异步能力基于 Redis 上的 asynq，服务本身可以在没有 Redis 的情况下运行（相关任务降级为同步/跳过，见 README.md 的 Tech Stack 说明）。Docker 单机测试可以全部关掉；正式售卖建议配一个独立 Redis 容器，通过host指向它。

其他常用项速查

另外，所有配置项都支持环境变量覆盖（.替换为_，如SERVER_PORT=9000），对不想落盘密钥的 Docker 用户很友好（见 config.go）。

生产环境最佳实践清单

1. 三把密钥用openssl rand -hex 32各生成一个，写进挂载的config.yml或环境变量，绝不使用默认值；
2. server.mode: release，并把web.admin_path改成不易猜测的随机路径，降低自动化扫描风险；
3. 挂载三个数据卷（db/uploads/logs），定期备份db/+uploads/+config.yml三件套——迁移脚本也明确要求三者一起备份（见 dujiao-next-manager.sh 的注释：app.secret_key缺失将无法解密已存储的敏感信息）；
4. 开启后台 TOTP 2FA：管理端登录自带二次验证，密钥由app.secret_key体系保护；
5. 前置反向代理时正确配置trusted_proxies，并终止 TLS；
6. 忘记后台密码 / 2FA 被锁无需重建容器，运维子命令已内置在同一二进制中：

docker exec -it dujiao-next ./dujiao-next admin list-admins docker exec -it dujiao-next ./dujiao-next admin reset-password docker exec -it dujiao-next ./dujiao-next admin reset-2fa

7. 拆分 HTTP 与后台任务（流量较大时）：同一二进制支持三种运行模式，通过--entrypoint覆盖容器 CMD 即可：

# 只跑 HTTP 服务 docker run ... --entrypoint ./dujiao-next dujiaonext/dujiao-next:latest -mode api # 只跑后台 worker docker run ... --entrypoint ./dujiao-next dujiaonext/dujiao-next:latest -mode worker

常见问题 FAQ

Q1：容器启动即退出，日志提示「以下运行时密钥过弱、重复或仍为默认值」？A：app.secret_key、jwt.secret、user_jwt.secret三者有相同、为占位符或长度不足。重新执行 3 次openssl rand -hex 32，确保互不相同再重启。

Q2：没有 Redis 能跑吗？A：可以。把redis.enabled和queue.enabled都设为false，核心商城功能可用，依赖队列的异步任务会降级处理。正式环境仍建议配 Redis。

Q3：升级版本怎么做？A：docker pull dujiaonext/dujiao-next:latest后重建容器即可。数据都在挂载卷里，升级不会丢数据；配置不兼容时启动阶段会在动数据库之前干净退出，不会产生半成品迁移。

Q4：商城首页正常，但后台 404？A：检查你访问的路径是否与web.admin_path一致，以及反向代理是否把该前缀也转发到了 8080 端口（/api、/uploads、/health同为保留前缀）。

Q5：SQLite 够用吗？A：默认 SQLite 连接池固定为 1（项目对其做了专门的事务约束设计），中小流量零运维即可。需要更高并发或外置数据库时，把database.driver改为postgres并填写连接串。

总结

得益于「前端内嵌单二进制」的设计，Dujiao-Next 的 Docker 部署没有网络拓扑、没有 Nginx 配置、没有跨容器通信——你只需要管好一份 config.yml 和三个数据卷。完成本文步骤后，一个可对外售卖数字商品的电商站点就跑起来了。