codex-register 生产部署指南Docker Compose、数据持久化与数据库备份一次讲清【免费下载链接】codex-register项目地址: https://gitcode.com/gh_mirrors/co/codex-registercodex-register是一个管理 OpenAI 账号的 Web UI 系统支持多邮箱服务、并发批量注册、代理管理和账号管理。本文面向新手完整讲清三件事用 Docker Compose 一键部署 codex-register、通过卷挂载实现数据持久化、配置 SQLite/PostgreSQL 数据库备份让你的生产环境稳定、可恢复。一、部署前需要准备什么在开始之前确认你的服务器满足以下条件项目要求Docker已安装并可运行Docker Composev2 及以上端口默认15555可按需修改Python无需本地安装全部在容器内运行项目结构上部署相关的三个核心文件分别是docker-compose.yml —— 容器编排配置生产部署首选Dockerfile —— 镜像构建定义基于python:3.11-slimwebui.py —— Web UI 程序入口二、Docker Compose 一键部署步骤这是最简单、也最推荐的部署方式全程只需 3 条命令# 1. 克隆项目 git clone https://gitcode.com/gh_mirrors/co/codex-register cd codex-register # 2. 构建并后台启动 docker-compose up -d --build # 3. 查看容器日志确认启动成功 docker-compose logs -f看到日志中监听地址输出后访问http://服务器IP:15555即可进入登录页。⚠️第一步必做把 docker-compose.yml 中的WEBUI_ACCESS_PASSWORD: admin123改成你自己的强密码默认密码等于裸奔。一键改端口x-webui-port 锚点技巧很多人不知道的是docker-compose.yml 顶部有这样一行x-webui-port: webui-port 15555这个值通过 YAML 锚点webui-port/*webui-port同时绑定到三处宿主机端口映射docker-compose.yml容器内WEBUI_PORT环境变量docker-compose.yml健康检查访问地址docker-compose.yml也就是说改这一个数字就够不会出现端口映射改了、容器内端口没改导致健康检查一直失败的经典坑。常用运维命令速查docker-compose logs -f # 实时查看日志 docker-compose restart webui # 重启服务 docker-compose down # 停止并移除容器数据卷不受影响 docker-compose up -d --build # 更新代码后重新构建并启动docker-compose.yml中还配置了restart: unless-stopped服务器重启后容器会自动拉起无需额外配置。三、数据持久化为什么两个挂载卷缺一不可打开 docker-compose.yml你会看到这两行卷挂载volumes: - ./data:/app/data - ./logs:/app/logs这就是生产部署的核心。codex-register 的所有关键数据分布在这两个目录宿主机目录容器内目录存什么丢了会怎样./data/app/data数据库文件、账号数据、设置所有账号、Token、服务配置全丢./logs/app/logs运行日志排障时无据可查 原理一句话容器是易失的docker-compose down或重建镜像都会销毁容器文件系统而挂载的./data和./logs在宿主机上容器怎么折腾都不会丢。这也是官方 README 反复强调挂载data目录的原因。如果你不用 Compose、直接docker run等价写法是docker run -d \ -p 15555:15555 \ -e WEBUI_ACCESS_PASSWORD你的强密码 \ -v $(pwd)/data:/app/data \ -v $(pwd)/logs:/app/logs \ --name codex-register \ ghcr.io/yunxilyf/codex-register:latest生产环境建议换成命名卷或独立磁盘默认用相对路径./databind mount已经够用但如果数据量大更推荐volumes: app-data: app-logs: services: webui: volumes: - app-data:/app/data - app-logs:/app/logs volumes: app-data: app-logs:命名卷由 Docker 管理、IO 性能更好进一步讲究的话可以在volumes定义中用driver_opts把device指到独立磁盘或 SSD 分区。四、数据库SQLite 默认PostgreSQL 可选codex-register 基于 SQLAlchemy默认使用SQLite库文件在data/database.db会话管理逻辑见 src/database/session.py。什么时候该上 PostgreSQL单实例 中等数据量 →SQLite 完全够用零运维需要多节点访问、高并发写入、独立备份策略 → 换远程 PostgreSQL接入远程 PostgreSQL 的方法通过环境变量指定连接字符串即可APP_DATABASE_URL优先于数据库内的设置# 写入 docker-compose.yml 的 environment 中 APP_DATABASE_URL: postgresql://用户:密码主机:5432/库名实现细节程序启动时读取该变量并自动转换为 psycopg 驱动连接串src/database/session.py、src/config/settings.py。注意PostgreSQL 模式下程序跳过自动表结构迁移src/database/session.py 中migrate_tables仅对 SQLite 生效升级前建议先备份。五、数据库备份三层防线第 1 层内置一键备份最省心项目在「系统设置」页面提供了数据库管理功能对应后端接口 src/web/routes/settings.py备份调用POST /api/settings/database/backup自动把数据库文件复制为data/backups/database_backup_时间戳.db查看状态GET /api/settings/database返回库文件大小、账号数、任务数清理过期任务POST /api/settings/database/cleanup可删除 N 天前的已完成任务记录备份文件默认落在data/backups/目录——由于data已挂载到宿主机这份备份天然就有一份主机外的副本直接定期打包上对象存储/另一台机器即可。第 2 层SQLite 热备份命令推荐加入 crontab对 SQLite 最安全的备份方式是在线复制而不是直接cp直接复制可能拷到写入一半的库sqlite3 /path/to/data/database.db .backup /path/to/backup_$(date %F).db示例定时任务每天凌晨 3 点备份保留 14 天0 3 * * * sqlite3 /opt/codex-register/data/database.db .backup /opt/backup/codex_$(date \%F).db find /opt/backup -name codex_*.db -mtime 14 -delete第 3 层PostgreSQL 用户用 pg_dumppg_dump -h 主机 -U 用户 -F c codexdb codex_$(date \%F).dump恢复用pg_restore -d codexdb 备份文件.dump即可比复制整个数据目录可靠得多。备份验证定期做一次恢复演练备份的价值取决于能不能恢复。建议每月挑一份备份在测试环境执行恢复并登录确认账号数据完好这一步比任何备份策略本身都重要。六、生产环境安全清单部署完成后按这个清单过一遍已修改WEBUI_ACCESS_PASSWORD或APP_ACCESS_PASSWORD不再使用默认admin123已挂载./data:/app/data与./logs:/app/logs已配置数据库备份计划内置备份 定时任务双保险已为服务器配置防火墙仅放行必要端口对外访问建议在前面加一层反向代理如 Nginx并启用 HTTPS升级前已手动备份一次数据库七、常见部署问题排查现象原因解决方法端口访问不通x-webui-port三处不一致手动改端口时漏改统一改 docker-compose.yml 顶部的锚点值健康检查一直失败容器内WEBUI_PORT与实际监听不一致同上用锚点统一端口重启后数据丢失忘记挂载./data卷补上卷挂载旧数据无法找回所以备份升级后表结构报错PostgreSQL 不执行自动迁移升级前先备份必要时手动比对表结构忘记访问密码数据库里存的密码忘了启动时临时用APP_ACCESS_PASSWORD环境变量覆盖重新设置后移除写在最后回顾一下 codex-register 生产部署的三个关键点Docker Compose 部署改好密码和端口锚点docker-compose up -d一条命令上线数据持久化./data和./logs两个挂载卷是数据的命根子数据库备份内置一键备份 定时任务 定期恢复演练三层防线缺一不可。按这个指南走完你的 codex-register 就具备了生产级的可用性。祝你部署顺利【免费下载链接】codex-register项目地址: https://gitcode.com/gh_mirrors/co/codex-register创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考