兔狲 · 公众号助手（wx-publish-studio）

兔狲 · 公众号助手（wx-publish-studio）是一款支持完全自托管的微信公众号图文工作台。该项目旨在为创作者和企业提供一个数据私有、所见即所得的排版与草稿管理环境，通过单条 Docker Compose 命令即可完成全套服务的部署。

• GitHub：https://github.com/k7airos/wx-publish-studio

核心功能与工作流边界

该工具聚焦于图文内容的创作与草稿管理，明确了清晰的功能边界，确保用户数据的安全与可控。

• 正文撰写：内置编辑器支持直接粘贴 Markdown 格式文本与图片，原样保留原有结构与媒体资源。
• 样式与封面配置：提供右侧面板用于调整字号、行间距及提示块等排版细节。封面支持根据标题自动生成，也允许上传自定义图片。
• 移动端预览：实时生成手机屏幕尺寸的完整预览效果，确保正文与封面的呈现与最终发布效果一致。
• 草稿箱同步：确认无误后，内容将直接写入已连接的微信公众号草稿箱。支持对同一篇草稿进行覆盖更新，重复提交不会产生冗余记录。

功能边界说明：本项目仅负责写入草稿箱，不提供群发、定时群发或数据统计功能，也不读取公众号内已发布的内容。最终的发布操作仍需用户在微信公众平台后台手动完成。

架构模式：内置中继与自定义中继

为了适应不同规模团队的网络环境与安全策略，系统提供了两种运行模式：

• 模式 A（默认，同栈自带中转）：开箱即用。Docker Compose 会自动拉起一个内置的中继服务（Relay），无需用户额外准备中转服务器。该中继仅在容器网络内部通信，不暴露宿主端口。
• 模式 B（自定义中转）：适合已有企业级网关或中继服务的团队。用户需在 .env 文件中配置自有的中继地址（需实现特定的 API 契约），此时 Compose 将不会启动内置的中继容器。

快速部署指南

部署环境要求一台 2 核 4G 起步的服务器，并安装 Docker Engine 24+ 及 Docker Compose v2.2+。Worker 组件内置 Chromium，建议为其预留 1GB 以上内存。

方式一：使用已发布镜像（推荐）

1. 获取代码：克隆仓库并进入目录。
2. 生成密钥：复制 .env.example 为 .env，并使用 openssl rand -hex 32 命令生成 5 个独立的密钥，分别填入 POSTGRES_PASSWORD、CREDENTIAL_ENCRYPTION_KEY、BOOTSTRAP_SECRET、PIPELINE_WORKER_TOKEN 和 RELAY_JWT_SECRET。
3. 配置域名：在 .env 中设置 APP_ORIGIN，该值必须与浏览器实际访问的地址（协议、域名、端口）完全一致。
4. 启动服务：执行 docker compose up -d --wait，等待四个容器全部达到健康状态。
5. 初始化中继：运行 bash scripts/relay-init.sh 创建中继管理员并生成访问令牌，随后再次执行启动命令使配置生效。

方式二：从源码构建

若网络环境无法拉取官方镜像，可将启动命令替换为 docker compose up -d --build --wait。系统将基于本地代码及固定的上游提交进行构建，首次冷构建约需 10-20 分钟。

访问与公众号连接配置

出于安全考虑，应用默认仅绑定回环地址 127.0.0.1:18889。远程访问需通过 SSH 隧道转发，或使用 Nginx/Caddy 配置 HTTPS 反向代理，并同步修改 .env 中的 APP_ORIGIN。

连接公众号的具体步骤如下：

1. 使用 BOOTSTRAP_SECRET 登录工作台。
2. 进入「公众号」页面，按向导填写公众号名称、AppID 和 AppSecret。
3. 配置 IP 白名单：将实际调用微信接口的中转服务器公网 IP（模式 A 即为当前服务器公网 IP）添加至微信公众平台的「API IP 白名单」中。该配置存在生效延迟，将在首次存入草稿箱时进行验证。
4. 撰写文章、调整排版并预览后，点击「存入草稿箱」即可完成同步。

数据存储、备份与升级规范

系统通过四个独立的 Docker 卷管理数据，任何备份操作都必须完整包含以下内容及 CREDENTIAL_ENCRYPTION_KEY，否则无法完整还原：

• app-data：应用私有数据（上传的封面与正文素材）。
• database-data：PostgreSQL 数据库（文章、排版、公众号连接及加密凭据）。
• worker-data：Worker 的账号登记、任务队列与运行结果。
• relay-data：同栈中继的管理员、访问令牌与审计日志（仅模式 A 存在）。

运维注意事项：

• 严禁执行 docker compose down -v，该命令会永久删除上述数据卷，导致用户数据不可恢复。
• 升级流程：修改环境变量或升级版本时，需先执行 git pull 和 docker compose pull，随后运行 docker compose up -d --wait 以应用数据库迁移与新镜像。
• 已知限制：当前版本仅支持单实例运行，Worker 采用本地 JSON 队列，多副本会导致数据覆盖。系统默认为单用户 Bootstrap 模式，暂不提供多用户配额与自助注册功能。

此外，项目在构建阶段内置了品牌文案中性化检查机制（scripts/brand-copy.ts），确保最终运行镜像中不包含任何上游编辑器包的默认特定公众号名称，保障自托管环境的纯净度。