doccano二次开发全攻略：从环境搭建到PR提交的进阶路径

2026-04-21 11:18:42作者：冯爽妲Honey

项目速览实战指南

架构概览与核心模块

doccano采用前后端分离架构，基于Docker Compose实现服务编排。核心技术栈包括Django后端、Vue.js前端、PostgreSQL数据库及Celery任务队列。系统架构如图所示：

图：doccano基于Docker Compose的服务架构，展示了Web服务器、应用服务器、数据库及任务队列之间的交互关系

核心功能模块路径：

后端服务：backend/
  - API层：backend/api/
  - 数据导入：backend/data_import/
  - 数据导出：backend/data_export/
  - 标签管理：backend/labels/
  - 项目管理：backend/projects/

前端应用：frontend/
  - 组件库：frontend/components/
  - 页面路由：frontend/pages/
  - 状态管理：frontend/store/
  - API调用：frontend/repositories/

开发环境搭建指南

环境要求

Docker Engine 20.10+
Docker Compose 2.0+
Git 2.30+
Python 3.8+ (可选，本地开发)

代码获取与初始化

git clone https://gitcode.com/gh_mirrors/doc/doccano
cd doccano

容器化部署

# 构建并启动服务
docker-compose -f docker/docker-compose.prod.yml up -d --build

# 初始化数据库
docker exec -it doccano_backend_1 python manage.py migrate

# 创建管理员账户
docker exec -it doccano_backend_1 python manage.py create_admin --username admin --password admin --email admin@example.com

服务启动后，访问http://localhost:8080即可打开应用界面。默认管理员账户为admin/admin。

开发实战核心技巧

项目创建功能实现

项目创建是doccano的基础功能，涉及前后端协同开发。以下是实现自定义项目类型的关键步骤：

后端模型扩展：在backend/projects/models.py中添加新的项目类型

class CustomProject(Project):
    custom_field = models.CharField(max_length=100, blank=True)
    
    class Meta:
        proxy = True  # 非数据库表继承
        
    def get_task_type(self):
        return "custom"

前端界面开发：在frontend/components/project/ProjectTypeField.vue中添加类型选项

<template>
  <v-select
    v-model="projectType"
    :items="projectTypes"
    label="Project Type"
  >
    <template v-slot:item="{ item }">
      <div>{{ item.text }}</div>
    </template>
  </v-select>
</template>

<script>
export default {
  data() {
    return {
      projectTypes: [
        { value: 'sequence_labeling', text: 'Sequence Labeling' },
        { value: 'text_classification', text: 'Text Classification' },
        { value: 'custom', text: 'Custom Project' }  // 新增类型
      ]
    }
  }
}
</script>

项目创建界面如图所示：

图：doccano项目创建表单，展示项目名称、描述和类型选择等核心字段

标注功能开发示例

以命名实体识别(NER)功能为例，核心实现位于frontend/components/tasks/sequenceLabeling/目录。以下是添加自定义实体类型的实现步骤：

定义实体类型：在backend/label_types/models.py中添加新实体类别

class EntityType(LabelType):
    color = models.CharField(max_length=7, default="#FF0000")
    
    class Meta:
        verbose_name = "Entity Type"

前端标注组件：修改frontend/components/tasks/sequenceLabeling/SequenceLabeling.vue

// 添加自定义实体样式
computed: {
  entityStyles() {
    return {
      'Person': { backgroundColor: '#ffcccc' },
      'Organization': { backgroundColor: '#ccffcc' },
      'CustomEntity': { backgroundColor: '#ccccff' }  // 新增实体样式
    }
  }
}

NER标注界面效果如图所示：

图：doccano命名实体标注界面，展示文本中不同实体类型的高亮显示效果

协作规范与流程

分支管理策略

main：生产环境分支，保持稳定可部署状态
develop：开发主分支，包含最新开发特性
feature/xxx：新功能分支，从develop创建，完成后合并回develop
fix/xxx：bug修复分支，从main创建，修复后同步到main和develop

代码提交规范

采用Conventional Commits规范，格式如下：

<类型>[可选作用域]: <描述>

[可选正文]

[可选脚注]

类型说明：

feat：新功能
fix：缺陷修复
refactor：代码重构
docs：文档更新
test：测试相关
chore：构建/工具相关

示例：

feat(projects): add custom project type selection

- Add 'Custom Project' option in project creation form
- Add database migration for custom field
- Update API documentation

PR提交流程

确保代码通过所有测试：

# 后端测试
cd backend
pytest

# 前端测试
cd frontend
yarn test

提交PR到develop分支，PR描述需包含：
- 功能实现细节
- 测试方法
- 相关文档更新
- 截图（如UI变更）
代码审查通过后由项目维护者合并

问题排查与优化

常见问题解决

容器启动失败

检查端口占用情况：

netstat -tulpn | grep 8080  # 检查Web端口
netstat -tulpn | grep 5432  # 检查数据库端口

查看容器日志：

docker logs doccano_backend_1
docker logs doccano_db_1

数据库迁移问题

# 生成迁移文件
docker exec -it doccano_backend_1 python manage.py makemigrations

# 应用迁移
docker exec -it doccano_backend_1 python manage.py migrate

# 重建数据库（开发环境）
docker exec -it doccano_backend_1 python manage.py flush

性能优化建议

数据库优化：
- 为频繁查询字段添加索引
- 优化backend/examples/models.py中的Example查询
前端性能：
- 实现列表虚拟滚动：frontend/components/example/DocumentList.vue
- 优化大型标注数据的渲染逻辑
API优化：
- 实现数据分页：backend/api/views.py中的ExampleViewSet
- 添加缓存层：使用Redis缓存常用数据