listmonk 开发者环境搭建指南Go 后端 Vue 前端的双进程开发模式与生产构建【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk导读listmonk 是一个高吞吐、自托管的新闻通讯与邮件列表管理工具整体采用Go 后端 Vue 前端的双组件架构。开发者环境与生产环境的关键差异在于开发模式下前后端各自独立运行、支持热重载而生产环境则通过单二进制文件将所有静态资源内嵌交付。本篇指南基于仓库内 developer-setup.md 展开覆盖前置依赖、首次初始化、本地/容器化/DevContainer 三种开发运行方式以及make dist的生产构建全流程并结合 Makefile、dev/docker-compose.yml、config.toml.sample 与 cmd/init.go 源码逐层印证帮助你从零搭建一个可热重载、可调试的 listmonk 开发环境并理解其最终如何被打包为单个自包含二进制。双组件架构Go 后端与 Vue 前端为何要分开运行listmonk 由两个相对独立的技术栈组成见 developer-setup.md 开篇说明Go 后端负责 HTTP API、数据库访问、邮件发送SMTP/Postback、弹回处理、批量导入、订阅者/列表/活动管理及计划任务等核心业务。入口为 cmd/main.go通过 cmd/init.go 完成配置加载、数据库连接、SQL 查询预编译、消息器初始化与 HTTP 服务器装配。Vue 前端位于 frontend/是基于 Vue 2 BuefyBulma的管理面板通过/api/*与后端交互。另含独立的 email-builderVue 3 TypeScript邮件可视化编辑器构建产物被拷贝进前端资源目录。开发模式下两者独立运行分别拥有自己的开发服务器、端口与热重载机制互不阻塞。生产构建时二者合流前端构建产物被内嵌进 Go 二进制最终交付单文件应用。这也解释了为什么文档要求先分别启动两个进程而非像生产环境那样直接运行一个二进制。前置依赖根据 developer-setup.md 的 Pre-requisites 章节开发 listmonk 需要以下环境依赖用途备注go编译并运行后端项目使用 go.mod建议 clone 到 Go src 路径之外nodejsyarn编译并运行前端仅在参与前端开发时需要PostgreSQL后端的数据存储本地无安装时可用 demo DB 容器docker compose up demo-db替代从 dev/app.Dockerfile 可看到仓库开发镜像锁定的版本基线golang:1.24.1与node:16同时设置CGO_ENABLED0。当前仓库 frontend/package.json 使用yarn1.22.22packageManager 字段固定依赖 Vue^2.7.14、Buefy^0.9.25、vite^5.4.21与 vuex/vue-router/vue-i18n 等node 版本若与本仓库开发期基线差异过大尤其是 Node 16 这类 EOL 版本可能出现依赖安装或构建失败建议优先以容器化方式开发以获得一致的构建环境。关于 Postgres 连接参数的快速参考config.toml.sample 给出了后端默认的数据库配置段这正是开发环境需要准备的外部依赖[db] host localhost port 5432 user listmonk password listmonk # Ensure that this database has been created in Postgres. database listmonk ssl_mode disable max_open 25 max_idle 25 max_lifetime 300s # Optional space separated Postgres DSN params. eg: application_namelistmonk gssencmodedisable params 从 cmd/init.go 的initDB()实现可以看到这些字段会被拼装为 Postgres DSNhost... port... user... password... dbname... sslmode...并据此配置连接池SetMaxOpenConns/SetMaxIdleConns/SetConnMaxLifetime一一对应max_open、max_idle、max_lifetimeparams则作为额外的空格分隔 DSN 参数原样追加如application_namelistmonk gssencmodedisable。数据库本身database字段指定的库必须预先创建--install只负责建表与写入种子数据不会替你创建数据库。首次初始化克隆、配置、建库三步走克隆仓库文档给出的命令是git clone https://github.com/knadh/listmonk.git项目使用 go.mod见仓库根目录 go.mod因此建议克隆到 Go src 路径之外避免与 Go Modules 的目录约定冲突。当前仓库对应的克隆地址为https://gitcode.com/GitHub_Trending/li/listmonk。配置 config.tomlcp config.toml.sample config.toml # 编辑 config.toml填入你自己的数据库等配置config.toml.sample 只含两个段落[app]的address默认localhost:9000即开发服务器监听地址与[db]的数据库连接。在容器化开发中dev/config.toml 提供了另一套取值address 0.0.0.0:9000、db.host db、用户/密码/库名均为listmonk-dev与 dev 容器内的 Postgres 服务名对齐。小技巧若尚未生成配置文件后端还支持./listmonk --new-config直接在--config指定的路径生成一份示例配置见 cmd/init.go 与 cmd/init.go 的--new-config标志说明。首次构建与建库make dist # 构建 listmonk 二进制 ./listmonk --install # 首次执行数据库安装建表 种子数据--install交互式执行时会有提示并要求输入y确认从 cmd/install.go 可以看到安装流程包括读取并执行 SQL 建表installSchema、写入示例列表installLists、示例订阅者installSubs、示例模板installTemplates、示例活动installCampaign并可通过环境变量LISTMONK_ADMIN_USER/LISTMONK_ADMIN_PASSWORD最少 3/8 字符预置超级管理员若未设置则首次访问网页时引导创建。--install --idempotent变体会先检查settings表是否存在已初始化则跳过这在 docker-compose.yml 的容器入口命令./listmonk --install --idempotent --yes ...中被用来保证幂等启动。后续开发运行不需要再走make dist直接使用make run即可二者区别见下文。提示文档特别推荐 mailhog——一个带 Web UI 的独立 mock SMTP 服务器——用于开发与测试阶段的邮件收验。dev 容器套件中已内置 MailHogSMTP:1025、UI:8025本地开发也可自行启动并将 SMTP 配置指向它。运行开发环境本地、容器Makefile与 DevContainer 三种方式文档提供了三种开发运行方式运行成功后统一访问http://localhost:8080前端管理面板。方式一本地运行推荐用于日常前后端开发make run # 启动后端 dev server监听 :9000 make run-frontend # 启动 Vue 前端 dev server监听 :8080/api/* 代理到 :9000两个命令对应 Makefile 与 Makefile 的两个 targetmake run等价于CGO_ENABLED0 go run -ldflags... -X main.frontendDirfrontend/dist ./cmd。注意它通过main.frontendDir变量把frontendDir指向frontend/distcmd/main.go 的默认值正是frontend/dist意味着即使在后端 dev 模式下若前端目录已有构建产物也会被当作静态资源加载。make run-frontend等价于在 frontend/ 目录执行yarn dev即vite由 Vite 提供热更新。代理机制查看 frontend/vite.config.js 的server.proxy配置前端开发服务器会把以下路径代理到LISTMONK_API_URL || http://127.0.0.1:9000^/$^/(api|webhooks|subscription|public|health)^/admin/login^/(admin\/custom\.(css|js))也就是说/api/*、/webhooks/*、/subscription/*、/public/*、/health以及登录页与管理面板自定义 CSS/JS 等请求都会转发到运行在:9000的 Go 后端前端端口可用环境变量LISTMONK_FRONTEND_PORT覆盖默认 8080。这正是文档所述所有/api/*调用被代理到 :9000 应用的源码依据。方式二容器化运行Makefile 驱动make init-dev-docker # 构建镜像并初始化容器化数据库 make dev-docker # 启动整套容器套件前端 后端 PG MailHog Adminer make rm-dev-docker # 拆除整套容器连同数据库卷一起删除三个 target 的实现见 Makefileinit-dev-docker先build-dev-docker进入 dev/ 执行docker compose build然后执行docker compose run --rm backend sh -c make dist ./listmonk --install --idempotent --yes --config dev/config.toml——即在容器内完成构建 幂等建库使用的是 dev/config.toml。dev-docker进入 dev/ 执行docker compose up启动 dev/docker-compose.yml 定义的整套服务。rm-dev-docker执行docker compose down -v连同数据库数据卷一并清除属于彻底清理。从 dev/docker-compose.yml 可以看到套件包含 5 个服务服务端口说明backend9000Go 后端命令为make run-backend-docker使用dev/config.toml挂载整个仓库到容器front8080Vue 前端命令为make run-frontendLISTMONK_API_URLhttp://backend:9000db5432postgres:13账号listmonk-dev数据持久化于 volumemailhog1025(SMTP) /8025(UI)开发邮件捕获adminer8070数据库 Web 管理界面访问容器内:8080backend与front两个容器都挂载了宿主机整个仓库目录../:/app这正是 dev/README.md 所述的设计目标避免每次代码变更都完整docker build只需重启容器即可。dev/README 还指出前端代码改动无需任何额外操作yarn watch 目录挂载自动生效后端 Go 代码改动则需重新运行make dev-docker触发重新编译。另注意backend容器把宿主机 Go module 缓存挂载进容器${GOPATH:-${HOME}/go}/pkg/mod/cache可加速依赖拉取。方式三DevContainerVS Code 远程开发文档步骤在 VS Code 中打开仓库 → 命令面板Command Palette→ 选择Dev Containers: Rebuild and Reopen in Container。容器会自动完成数据库初始化并启动前后端服务。补充说明当前仓库截至本仓库快照并未在根目录包含.devcontainer/目录或docker compose up demo-db对应的一等服务定义源码检索未发现devcontainer相关文件demo-db服务也仅在本文档中被提及。因此DevContainer 与demo-db属于官方文档描述的能力/历史用法实际可用性取决于你克隆的上游仓库版本与 VS Code Dev Containers 扩展的远程容器探测逻辑在当前仓库内容器化开发的权威入口是 dev/docker-compose.yml 与 Makefile 的init-dev-docker/dev-docker流程建议优先使用该路径若确需 DevContainer可在 VS Code 中直接使用Rebuild and Reopen in Container后观察其自动探测结果或自行按 dev/app.Dockerfile 的基线golang:1.24.1 node:16编写容器配置。三种方式的取舍对比维度本地容器MakefileDevContainer依赖隔离依赖本机 Go/Node/Postgres完全隔离环境一致性最好同容器但配置在 IDE 内启动速度最快无容器开销首次构建镜像较慢之后仅重启容器首次构建镜像较慢热重载后端需重编译前端 yarn watch前端自动后端需重启容器同容器适用场景日常快速迭代前端后端联调环境统一/多人协作/不想污染本机偏好 IDE 内一体化开发前端开发内部结构速览文档指向了 frontend/README.md 作为前端结构的入门。要点如下有助于在开发中快速定位全局注入frontend/src/main.js 中全局挂载 Buefy、vue-i18n以及$api来自 frontend/src/api/index.js 的 API 调用集合与$utilsfrontend/src/utils.js组件内以this.$api、this.$utils访问常量集中在 frontend/src/constants.js。全局状态采用 Vuex 集中存储几乎所有 API 响应models定义在 frontend/src/store/index.js并有全局loading状态如loading.campaigns供各组件显示 spinner。字段命名约定重要GET API 响应的 JSON 字段名会被自动 camelCase 化如content_type→contentType而向后端发送时需手动 snake_case例外是/api/config、/api/settings等调用通过api/index.js中的preserveCase: true保留原样。改动前端代码时务必遵守这一约定否则字段名不匹配会导致联调异常。图标方案Buefy 默认用 Material Design Iconsmdi-前缀listmonk 只选取少量图标打包为 web fontFontello。需要新增图标时将 frontend/fontello/config.json 拖入 Fontello 官网选择图标下载后将config.json、fontello.woff2、css/fontello.css分别覆盖回 frontend/fontello、frontend/src/assets/icons/。生产构建make dist产出单文件二进制make dist是文档给出的生产构建命令其含义见 Makefile是依次执行build、build-frontend与pack-bin三个步骤buildMakefileCGO_ENABLED0 go build -o listmonk -ldflags-s -w -X main.buildString... -X main.versionString... ./cmd。-ldflags注入版本与构建信息CGO_ENABLED0产出纯静态二进制。版本号解析逻辑在 Makefile优先取 git describe 标签其次 VERSION 文件最后回退v0.0.0。build-frontendMakefile先后构建 email-builderyarn build产物frontend/email-builder/dist拷入frontend/public/static/email-builder与主前端frontend目录内yarn build产物 frontend/dist。构建前还会先执行依赖安装yarn install产物跟随 frontend/package.json 的prebuild跑一次 ESLint 检查。pack-binMakefile调用 stuffbin 将静态资源塞进二进制——即 Makefile 定义的STATIC清单config.toml.sample、schema.sql、queries/、permissions.json、static/public → /public、static/email-templates、frontend/dist → /admin、i18n/ → /i18n。运行时 cmd/init.go 的initFS()会先尝试从可执行文件解出内嵌文件系统stuffbinUnStuff解不出时例如直接用go run开发运行才回退到本地文件系统从appDir、frontendDir及用户指定的static-dir/i18n-dir按需加载静态资源——这正是make run与make dist产物行为差异的底层原因。最终listmonk是一个自包含二进制内置数据库 schema、SQL 查询、Go 后端、Vue 管理面板与邮件模板可单独部署无需附带任何静态目录--install首次初始化时从内嵌 FS 读 schema 与种子数据。常用开发命令速查表命令作用对应实现make run启动 Go 后端 dev server:9000Makefilemake run-frontend启动 Vue 前端 dev server:8080API 代理到 9000Makefilemake init-dev-docker构建开发镜像 幂等初始化容器内数据库Makefilemake dev-docker启动整套开发容器front/backend/PG/MailHog/AdminerMakefilemake rm-dev-docker拆除容器并删除数据库卷Makefilemake dist生产构建Go 二进制 前端构建 stuffbin 内嵌静态资源Makefilemake test运行全部 Go 测试go test ./...Makefile./listmonk --install首次数据库初始化建表 种子数据cmd/install.go./listmonk --install --idempotent --yes幂等建库用于脚本/容器首次启动cmd/install.go./listmonk --new-config在--config指定路径生成示例配置cmd/init.go./listmonk --version显示构建版本信息cmd/main.go小结listmonk 的开发环境搭建核心在于理解前后端分离、按需合流的运行模型开发期用make runmake run-frontend双进程协作或容器化的make init-dev-dockermake dev-docker借助 Vite 代理打通:8080与:9000交付期用make dist把 Vue 构建产物经 stuffbin 内嵌进 Go 二进制得到单一自包含可执行文件。配置上只需准备一份config.toml与一个可用的 PostgreSQL 实例容器套件已替你备好。开发过程中遇到问题可参考 dev/README.md容器套件说明与 frontend/README.md前端结构与命名约定并善用make test验证后端改动。【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考