doccano Docker 部署实战：使用 Docker Compose 快速搭建标注平台并启用数据导出功能

数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载本指南以 doccano 官方 Docker 快速开始文档仓库内路径 docker/docs_docker-quickstart_Version2.md为骨架完整讲解如何用 Docker 与 Docker Compose 在本机运行 doccano并确保标注数据导出功能可用。读完本文你将掌握从克隆仓库、构建镜像、启动多服务、创建超级用户到导出数据排障的完整闭环同时理解 Celery 任务队列在导入/导出链路中的核心作用与源码级实现。部署前必读doccano 的两种容器化形态doccano 的 Docker 支持存在两条路径对应仓库内不同的构建与编排文件。快速开始文档描述的是“单 Compose 文件拉起 Django 后端 前端 UI Celery worker Redis 任务队列”的组合而当前仓库实际提供的是单容器镜像docker/Dockerfile一个容器内同时运行 gunicornWeb 服务与 Celery任务队列入口脚本为 tools/run.sh默认使用 SQLiteDATABASE_URLsqlite:////data/doccano.db并通过卷doccano-db:/data持久化端口映射8000:8000。适合单机快速试用。生产级 Docker Composedocker/docker-compose.prod.yml采用三层架构由backendDjango gunicorn、celeryworker、flowerCelery 监控面板、rabbitmq消息代理、nginx前端与反向代理、postgres数据库共 6 个服务组成。官方架构图如下单容器形态的架构则如下所有进程Django、gunicorn、Celery与 SQLite 数据库都封装在同一个容器内客户端通过绑定的 8000 端口访问两种形态的取舍很清晰单容器开箱即用、依赖最少适合个人体验与小型项目生产 Compose 将 Web、异步任务、消息代理与数据库解耦支持横向扩展与任务监控适合团队协作环境。官方文档对docker/目录各文件的职责有详细说明可参考 docs/developer_guide.md。第一步克隆仓库首先获取 doccano 源码。本仓库为镜像仓库实际使用时克隆上游即可git clone https://github.com/doccano/doccano.git cd doccanoWindows 开发者注意仓库 README 特别提示需要配置 Git 正确处理行结束符否则后续启动服务时可能遇到status code 127错误。推荐使用如下克隆方式git clone https://github.com/doccano/doccano.git --config core.autocrlfinput克隆完成后仓库顶层包含四个与部署直接相关的目录/文件路径作用backend/Django REST API 后端Python 3.8、Django 4.0、Poetry 管理依赖frontend/Nuxt.js 前端Node.js Yarn 构建docker/Dockerfile、nginx 配置与 Compose 编排文件tools/容器内启动脚本run.sh、prod-django.sh、prod-celery.sh、prod-flower.sh等第二步构建并启动容器快速开始文档给出的启动命令为docker compose -f docker/docker-compose.yml up --build该命令按文档意图会启动以下四类服务Django backend提供 REST APIFrontend UI标注界面Celery worker负责异步任务数据导出必需RedisCelery 任务队列的消息代理。仓库现状说明当前仓库docker/目录下实际提供的是 docker/docker-compose.prod.yml并未包含文档中引用的docker/docker-compose.yml。若严格按文档命令执行会因文件不存在而失败。因此下文给出两条基于仓库真实文件、可直接运行的路径。方式 A单容器一键启动推荐快速体验使用 docker/Dockerfile 构建镜像或直接拉取官方镜像docker pull doccano/doccano docker container create --name doccano \ -e ADMIN_USERNAMEadmin \ -e ADMIN_EMAILadminexample.com \ -e ADMIN_PASSWORDpassword \ -v doccano-db:/data \ -p 8000:8000 doccano/doccano docker container start doccano容器启动后tools/run.sh 会自动执行初始化流程wait_for_db→migrate→create_roles→ 依据ADMIN_USERNAME/ADMIN_PASSWORD/ADMIN_EMAIL环境变量调用create_admin创建超级用户然后并行拉起 gunicorn 与 Celery worker。这也解释了为什么单容器模式下导出功能开箱即用——Celery 与 Web 进程同处一个容器。如需使用最新特性可指定nightly标签docker pull doccano/doccano:nightly。方式 B生产级 Docker Compose团队协作推荐先在仓库根目录创建.env文件README 给出的变量格式参见 README.md# platform settings ADMIN_USERNAMEadmin ADMIN_PASSWORDpassword ADMIN_EMAILadminexample.com # rabbit mq settings RABBITMQ_DEFAULT_USERdoccano RABBITMQ_DEFAULT_PASSdoccano # database settings POSTGRES_USERdoccano POSTGRES_PASSWORDdoccano POSTGRES_DBdoccano然后启动全部服务docker-compose -f docker/docker-compose.prod.yml --env-file .env up该 Compose 文件docker/docker-compose.prod.yml启动的服务与端口如下服务镜像/入口端口职责nginxdoccano/doccano:frontend80:8080前端静态资源 反向代理/v1/、/admin/、/swagger/、/static/、/media/backenddoccano/doccano:backend入口 tools/prod-django.sh内部 8000Django gunicorn执行迁移、创建角色与超级用户celery同 backend 镜像入口 tools/prod-celery.sh-消费导入/导出等异步任务flower同 backend 镜像入口 tools/prod-flower.sh5555:5555Celery 任务监控面板FLOWER_BASIC_AUTH控制访问rabbitmqrabbitmq:3.10.7-alpine5672:5672Celery 消息代理postgrespostgres:13.3-alpine内部 5432主数据库nginx 的具体路由规则见 docker/nginx/default.conf/v1/、/admin/、/swagger/反向代理到backend:8000/static/与/media/直接以卷目录提供服务client_max_body_size上限为 100M。Worker 进程数由 nginx 模板 docker/nginx/nginx.conf.template 中的WORKER_PROCESSES环境变量控制。第三步访问 Web UI单容器模式浏览器打开 http://localhost:8000生产 Compose 模式nginx 映射在宿主机 80 端口浏览器打开 http://localhost如果只想先看看标注界面而不安装任何组件也可以直接访问仓库自带的 frontend/pages/demo/ 下的演示页面源码了解交互形态。第四步创建超级用户快速开始文档建议在容器启动后另行创建超级用户。单容器模式由于run.sh已根据环境变量自动创建且create_admin对已存在用户会友好提示“already exists”通常无需手动操作生产 Compose 模式同样由 tools/prod-django.sh 依据ADMIN_USERNAME/ADMIN_PASSWORD/ADMIN_EMAIL自动创建。如需在任何形态下手动创建或重置管理员可在新终端执行docker compose -f docker/docker-compose.prod.yml exec backend python manage.py createsuperuser该命令的底层实现可参考 backend/api/management/commands/create_admin.py它继承 Django 的createsuperuser支持--username、--password、--email、--noinput等参数并会在密码为默认值password时打印更换密码的警告。第五步使用 doccano完成登录后标准使用流程为创建项目在项目列表页选择项目类型文本分类、序列标注、序列到序列、语音转文本、意图检测、目标检测、分割、图像分类/描述等导入数据上传符合格式要求的数据文件导入同样是异步任务由 Celery worker 处理标注数据按项目类型进行标注标注结果实时保存导出数据在导出面板选择格式CSV / JSON / JSONL / fastText 等并触发下载。其中导入与导出都依赖 Celery worker 的正常运行这也是本文反复强调“worker 必须启动”的根本原因。第六步停止服务docker compose -f docker/docker-compose.prod.yml down停止容器不会删除数据因为数据库与媒体文件都保存在 Docker volume 中见下文。若连 volume 一并清理可追加-v参数——但请注意这会永久删除全部标注数据执行前务必确认。故障排查导出不工作——检查 Celery worker快速开始文档明确指出Celery worker 必须运行否则导出没有结果生产 Compose 的默认配置已包含 worker 服务。排查步骤如下docker compose -f docker/docker-compose.prod.yml logs worker若 worker 未启动或崩溃可重点观察是否等待数据库成功prod-celery.sh会先执行python manage.py wait_for_db消息代理rabbitmq与CELERY_BROKER_URL环境变量是否配置一致是否安装并导入了configCelery 应用backend/config/celery.py 通过autodiscover_tasks(related_namecelery_tasks)自动发现各 app 的异步任务。单容器模式下同样可以查看日志docker logs doccanotools/run.sh内置了进程守护逻辑每 10 秒检查一次 gunicorn 与 celery 进程任一进程崩溃会立即打印错误并以非零码退出方便定位问题。持久化数据单容器模式数据保存在名为doccano-db的 volume 中挂载至容器内/data对应 SQLite 文件doccano.db。容器停止、删除后数据仍在docker container stop doccano -t 5即可安全停服。生产 Compose 模式定义于 docker/docker-compose.prod.yml 末尾的四个 volume——postgres_data数据库、static_volume静态文件、media用户媒体/导出产物、tmp_fileFilePond 临时上传目录——分别持久化对应数据。深入原理为什么导出功能依赖 Celery导出不是同步的“下载文件”而是一条完整的异步任务链路源码证据如下前端发起导出请求向/v1/projects/project_id/download发送 POST携带format如JSONL与exportApproved是否仅导出已确认样本。视图调度 Celery 任务backend/data_export/views.py 中的DatasetExportAPI.post调用export_dataset.delay(...)立即返回task_id前端随后通过该task_id轮询任务状态。Worker 执行导出backend/data_export/celery_tasks.py 中的export_dataset任务被shared_task(autoretry_for(Exception,), retry_backoffTrue)装饰失败自动重试、指数退避按项目类型构造 formatter 与 writer将标注组装为 DataFrame 写出CSV/JSON/JSONL/fastText见 backend/data_export/pipeline/writers.py最后打包为 zip 文件返回路径。协作模式输出单一all.ext文件独立标注模式则按成员用户名逐个输出文件。前端下载成品DatasetExportAPI.get通过AsyncResult(task_id)检查task.ready()就绪后以FileResponse返回文件任务状态的通用查询接口见 backend/api/views.py 的TaskStatus。任务队列配置backend/config/settings/base.py 中CELERY_BROKER_URL默认回退为 SQLite 驱动sqlasqlite:///...生产 Compose 则显式配置为amqp://user:passrabbitmq结果后端使用django-dbdjango_celery_results。导出链路的正确性由测试覆盖例如 backend/data_export/tests/test_task.py 验证了文本分类、序列标注、关系抽取、目标检测、分割、语音转文本、图像分类/描述等各类型项目在“协作/独立 是否仅导出已确认”四种组合下的导出内容backend/data_export/tests/test_views.py 则验证了导出目录接口仅对项目管理员开放其他成员返回 403。环境变量与配置速查以下变量在容器化部署中常用均可在单容器docker run -e或 Compose 的.env中设置变量说明默认值ADMIN_USERNAME/ADMIN_PASSWORD/ADMIN_EMAIL启动时自动创建的超级用户凭据无必填DATABASE_URL数据库连接串dj-database-url 格式单容器为sqlite:////data/doccano.dbCELERY_BROKER_URLCelery 消息代理地址未设置时回退 SQLiteSECRET_KEYDjango 密钥生产环境务必更换change-me-in-productionDEBUG调试模式开关生产镜像为FalsePORT/WORKERSgunicorn 监听端口与进程数8000/2CELERY_WORKERSCelery worker 并发数2FLOWER_BASIC_AUTHFlower 监控面板的user:pass认证未设置则不启动 FlowerMAX_UPLOAD_SIZE单文件上传上限10737418241GBIMPORT_BATCH_SIZE数据导入批次大小1000延伸阅读README.mdDocker 单容器、Docker Compose、pip 三种安装方式的官方速览docs/install_and_upgrade_doccano.md完整的系统要求、pip/源码安装、升级与数据迁移说明docs/developer_guide.mddocker/目录各文件职责与两种架构图的官方说明docker/Dockerfile 与 docker/Dockerfile.prod、docker/Dockerfile.nginx镜像构建细节多阶段构建、依赖安装、入口脚本tools/run.sh、tools/prod-django.sh、tools/prod-celery.sh、tools/prod-flower.sh容器启动与初始化流程backend/data_export/导出功能的完整源码视图、Celery 任务、格式器、写入器与测试赞分享数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载相关推荐docker-compose一键部署doccano企业级标注平台搭建指南docker compose一键部署doccano企业级标注平台搭建指南 引言标注平台的企业级挑战与解决方案 你是否还在为团队协作标注数据而烦恼手动搭建标数据标注后端前端3步搞定跨平台字体统一PingFangSC免费字体解决方案3步搞定跨平台字体统一PingFangSC免费字体解决方案 还在为不同设备上字体显示效果参差不齐而烦恼吗PingFangSC字体为您提供了一套完整的免费商用前端企业级IM平台部署实战Docker Compose快速搭建OpenIM Server企业级IM平台部署实战Docker Compose快速搭建OpenIM Server 项目亮点与核心价值 OpenIM Server作为开源IM系统的佼佼者即时通讯后端微服务WebSocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考