数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载本文是 doccano开源机器学习标注工具官方 FAQ 的深度实践指南聚焦日常使用中最高频的八类问题创建与添加用户、修改密码、数据上传失败排查、修改访问端口、镜像升级、SQLite JSON1 扩展缺失以及 CSRF 校验失败。读完本文你将掌握通过 Django Admin 站点与命令行两种方式管理用户理解 doccano 成员-角色权限模型的底层实现并能独立定位数据导入失败与生产环境 CSRF 配置错误的根因。文中所有结论均以当前仓库源码backend、docker、docs为事实依据。一、用户与权限管理doccano 的所有标注行为都围绕用户—项目—角色三级模型展开。下面先从最基础的用户创建讲起。1.1 如何创建用户doccano 内置了 Django Admin 站点普通用户需要在 Admin 站点中创建。操作流程如下启动 doccano Web 服务webserver。登录 Admin 站点pip 安装方式下地址为http://localhost:{port}/admin/。下面的示例使用端口8000、用户名admin如果你在启动服务时设置了其他端口或用户名密码请使用你自己的值登录。登录 Admin 站点后点击Users用户点击右上角的ADD USER按钮为新用户输入用户名和密码后点击SAVE创建完成后新用户即可登录 doccano。建议先退出 Admin 站点再用新账号实际登录验证一次。源码补充非交互式创建管理员命令如果你需要以脚本化、非交互的方式批量初始化管理员账号例如在 CI 或容器化部署中仓库提供了专门的 Django management commandcreate_admin.py。该命令继承自 Django 内置的createsuperuser额外增加了--password参数python manage.py create_admin --username admin --password your_password --email adminexample.com从源码可以看到它的几个关键行为均有对应单元测试见 test_commands.py缺少--username或--password时抛出CommandError使用默认弱口令password时输出警告Warning: You should change the default password.若用户名已存在会输出User admin already exists.并正常退出不会中断脚本创建后立即为用户设置指定密码并输出Setting password for User admin.。在 Docker Compose 部署场景下管理员账号由 docker-compose.prod.yml 中的ADMIN_USERNAME、ADMIN_PASSWORD、ADMIN_EMAIL三个环境变量注入容器启动脚本会调用上述命令完成初始化。1.2 如何将用户添加到项目注意只有项目管理员Project Admin才能向项目添加新用户并且前提是该用户账号已存在参见上文如何创建用户。添加流程登录 doccano。点击进入你的项目。在左侧菜单中点击Members成员。如果你不是项目管理员侧边栏中不会出现Members入口。点击Add在 Add Member 表单中填写要加入项目的用户名及其角色。点击Save保存。保存后新用户即可访问该项目。源码补充成员管理的权限约束前端Members入口的显隐对应后端 API 的权限控制。成员相关视图位于 backend/projects/views/member.py其MemberList与MemberDetail均声明了permission_classes [IsAuthenticated IsProjectAdmin]即只有通过认证且具备项目管理员角色的用户才能列出、添加、删除或修改成员。权限类的实现见 backend/projects/permissions.pyIsProjectAdmin继承自RolePermission通过Member.objects.has_role(project_id, request.user, role_name)校验用户是否持有project_admin角色角色名可通过环境变量ROLE_PROJECT_ADMIN覆盖默认值为project_admin见 base.py。角色模型本身定义在 backend/roles/models.py而默认的三种角色project_admin、annotator、annotation_approver由管理命令 create_roles.py 在初始化时写入数据库已存在的角色会自动跳过、不会重复创建。另外值得注意的是 backend/projects/models.py 中Member模型的约束unique_together (user, project)同一用户在同一项目中只能有一个角色记录MemberManager.can_update()保证每个项目至少保留一名管理员——如果项目只剩唯一管理员则不能将其角色改为非管理员clean()会拒绝用户已在项目中分配角色的重复操作。1.3 如何修改用户密码修改密码同样通过 Admin 站点完成启动 doccano Web 服务。登录 Admin 站点pip 安装方式下为http://localhost:{port}/admin/。注意需要拥有 staff工作人员权限才能登录 Admin 站点。如果你没有相应权限请联系管理员代为修改。点击Users。点击你要修改密码的那个用户名在密码Password区域点击this form链接填写表单并修改密码修改完成后该用户下次登录请使用新密码。源码补充如果采用命令方式create_admin命令内部同样通过user.set_password(password)user.save()完成密码写入见 create_admin.pyDjango 会以 PBKDF2 等算法对密码做哈希存储Admin 站点的密码修改走的是 Django 内置认证逻辑二者底层一致。二、数据上传失败排查清单如果你在导入数据时失败请按以下清单逐项检查对应官方文档 FAQ我无法上传数据一节文件编码使用UTF-8编码最稳妥。文件名建议使用英文字母命名避免特殊字符。文件格式选择检查上传页面的文件格式单选按钮是否选对。JSON/JSONL 格式确认 JSON 数据合法。JSONL 文件可先抽取其中一行进行校验也可以使用在线 JSON 校验工具如 JSONLint或本地工具检查当 JSONL 很大时仅校验其中一行即可。CSV 格式确认 CSV 数据合法可用 Excel 或支持 CSV 导入的工具打开检查。缺少行数据文件不应包含空行blank line。缺少字段数据文件不应包含空字段blank field。提示校验文件格式时不需要使用真实完整数据。如果数据量大或涉密截取部分样本数据、或对敏感内容做脱敏后再校验即可。源码补充解析器的编码与格式处理上述清单中的编码与格式要求在导入管线中有对应的底层实现。数据解析模块位于 backend/data_import/pipeline/parsers.py编码自动检测parsers.py默认编码为Autodetect_encoding()使用chardet对小文件一次性检测、对大文件以增量方式UniversalDetector检测检测不到时回退为utf-8。这正是推荐 UTF-8的底层原因——非 UTF-8 文件虽可能被自动识别但识别失败会直接导致解析异常。JSON / JSONL 解析parsers.pyJSONParser对整份 JSON 执行json.loadJSONLParser则按行执行json.loads并携带行号LINE_NUMBER_COLUMN任何一行的JSONDecodeError都会被捕获并登记为FileParseException最后在导入接口中统一返回错误信息——这与 FAQ 中JSONL 抽一行校验的建议相互印证。CSV 解析parsers.py使用csv.DictReader按行读取空行会被跳过、空字段会以空字符串进入结果因此 FAQ 强调不要有空行、空字段以避免下游字段缺失。除上述格式外仓库还提供PlainParser、LineParser、TextFileParser、ExcelParser、FastTextParser__label__前缀与CoNLLParser支持IOB2、IOE2、IOBES、BILOU四种标注体系等解析器覆盖 doccano 支持的各类任务格式。此外上传大小由 base.py 中的MAX_UPLOAD_SIZE环境变量控制默认 1GB/文件如需调整可设置MAX_UPLOAD_SIZE。导入批次大小由IMPORT_BATCH_SIZE控制默认 1000 条/批见 base.py。三、修改端口号Docker Compose 部署Docker Compose 部署方式下前端 Nginx 默认监听宿主机的80端口并转发到容器内的8080。若80端口被占用可通过编辑 docker-compose.prod.yml 修改将nginx服务的ports段中80:8080改为your_port:8080nginx: image: doccano/doccano:frontend ports: - your_port:8080在backend服务的environment段新增CSRF_TRUSTED_ORIGINS环境变量指向新的访问地址backend: image: doccano/doccano:backend environment: ... DJANGO_SETTINGS_MODULE: config.settings.production CSRF_TRUSTED_ORIGINS: http://127.0.0.1:your_port改完后重新docker-compose up -d即可生效。为什么改端口必须同步配置CSRF_TRUSTED_ORIGINS因为浏览器会以新端口作为 Origin 发起跨站请求校验Django 的 CSRF 中间件会拒绝未列入信任来源的 Origin具体原理见本文第五节。四、升级到最新 doccano 镜像以 Docker Compose 方式部署时升级流程如下执行git pull拉取最新 doccano 代码。删除以下四个 Volumedoccano_node_modules、doccano_static_volume、doccano_venv、doccano_www。切勿删除doccano_postgres_data它保存着你的全部项目数据。重新构建 doccano 镜像。第 23 步对应的命令如下❯ docker volume ls DRIVER VOLUME NAME local doccano_node_modules local doccano_postgres_data local doccano_static_volume local doccano_venv local doccano_www ❯ docker volume rm doccano_node_modules doccano_static_volume doccano_venv doccano_www ❯ docker-compose -f docker-compose.prod.yml build --no-cache命令说明docker volume ls先列出当前存在的 Volume确认名称后再执行删除docker volume rm一次性删除四个可再生的构建缓存类 Volume前端 node_modules、静态文件、Python 虚拟环境、Web 产物它们可以在构建时自动重新生成docker-compose -f docker-compose.prod.yml build --no-cache显式指定生产 Compose 文件并关闭构建缓存确保重新构建得到的是包含最新代码的镜像。源码佐证当前仓库生产 Compose 文件中的 Volume 声明见 docker-compose.prod.ymlpostgres_data、static_volume、media、tmp_file。其中postgres_data挂载到 PostgreSQL 数据目录docker-compose.prod.yml是唯一的持久化数据来源升级时务必保留。五、CSRF 校验失败CSRF failed如果遇到 CSRF 校验失败请将CSRF_TRUSTED_ORIGINS环境变量设置为你的域名。例如域名是example.com则设置CSRF_TRUSTED_ORIGINSexample.com。在debug 模式下默认信任来源为http://127.0.0.1:3000、http://0.0.0.0:3000和http://localhost:3000。如果你使用 Docker Compose 部署请在 docker-compose.prod.yml 中为backend服务配置该变量backend: image: doccano/doccano:backend environment: ... DJANGO_SETTINGS_MODULE: config.settings.production CSRF_TRUSTED_ORIGINS: http://192.168.10.3:3000源码补充CSRF 配置的底层实现CSRF_TRUSTED_ORIGINS的读取逻辑位于 backend/config/settings/base.py默认从环境变量读取值为逗号分隔的列表CSRF_TRUSTED_ORIGINS env.list(CSRF_TRUSTED_ORIGINS, [])当DEBUG True时会先注入http://127.0.0.1:3000、http://0.0.0.0:3000、http://localhost:3000三个默认信任来源再追加环境变量中额外配置的来源——这正是文档中debug 模式默认值的来源生产环境配置 production.py 中DEBUG False此时没有任何默认信任来源因此生产部署若使用自定义域名或端口必须显式配置CSRF_TRUSTED_ORIGINS否则会复现本节描述的 CSRF 失败部署在反向代理后时还需注意 base.py 中的SECURE_PROXY_SSL_HEADER设置它会根据X-Forwarded-Proto请求头判断请求是否为 HTTPS若代理未正确传递该请求头同样可能引发 CSRF 相关的跳转/校验问题。六、django.db.utils.OperationalError: no such function: JSON_VALIDdoccano 在 SQLite 上使用了 Django 的JSONField因此需要 Python 的 sqlite3 库启用JSON1 扩展。如果你的 Python 安装未启用该扩展运行时会抛出django.db.utils.OperationalError: no such function: JSON_VALID。这个问题尤其容易出现在以下环境组合中macOS 且 Python 版本低于 3.7Windows 且 Python 版本低于 3.9。解决方案为 SQLite 启用 JSON1 扩展。可参考 Django 官方文档中关于 SQLite JSON1 扩展的说明在 Python 编译或运行层面启用该扩展。源码佐证默认数据库配置在 backend/config/settings/base.py 中为 SQLite 3django.db.backends.sqlite3数据库文件为db.sqlite3同时通过dj_database_url支持DATABASE_URL环境变量切换数据库base.py。从源码结构看在 SQLite 上使用 doccano 时建议优先排查本机 Python 的 SQLite 版本与 JSON1 支持如果你希望彻底规避此类问题也可以考虑切换到 PostgreSQL生产 Compose 文件即默认使用 PostgreSQL见 docker-compose.prod.yml。七、总结常见问题速查表问题一句话结论关键位置如何创建用户通过 Admin 站点/admin/的 Users 管理或使用create_admin命令create_admin.py如何添加用户到项目项目管理员在项目Members页面添加非管理员无入口member.py、permissions.py如何修改密码Admin 站点 Users → 用户详情 → password 区的this form链接Django Admin 内置功能数据上传失败检查 UTF-8 编码、英文字母文件名、格式选择、JSON/JSONL 合法性、无空行无空字段parsers.py修改端口号编辑docker-compose.prod.yml的nginx/ports并同步backend的CSRF_TRUSTED_ORIGINSdocker-compose.prod.yml升级镜像git pull→ 删除 4 个构建 Volume保留postgres_data→build --no-cachedocker-compose.prod.ymlJSON_VALID 报错为 Python 的 SQLite 启用 JSON1 扩展或改用 PostgreSQLbase.pyCSRF 失败显式配置CSRF_TRUSTED_ORIGINS生产环境无默认值base.py、production.py按照以上清单逐项排查绝大多数 doccano 日常使用与部署问题都能定位到明确原因如需深入某一环节可直接阅读上表列出的源码文件继续追踪。赞分享数据标注后端前端【免费下载链接】doccanoOpen source annotation tool for machine learning practitioners.项目地址https://gitcode.com/gh_mirrors/do/doccano点击查看免费下载相关推荐BiliBiliToolPro GitHub Actions 常见问题排查与运维实战指南BiliBiliToolPro GitHub Actions 常见问题排查与运维实战指南 本篇指南以 BiliBiliToolPro 仓库的 docs/ques后端任务调度工作流自动化TDengine 常见问题排查指南安装、连接、写入、查询、订阅与运维实战TDengine 常见问题排查指南安装、连接、写入、查询、订阅与运维实战 本指南基于 TDengine 官方 FAQ 文档整理覆盖从安装部署、客户端连接、数数据库时序数据库大数据物联网云原生Apache RocketMQ 运维管理实战集群搭建、mqadmin 命令与常见问题排查Apache RocketMQ 运维管理实战集群搭建、mqadmin 命令与常见问题排查 本文以 Apache RocketMQ 的运维管理为主线系统讲解单消息队列流处理后端上一篇AzurLaneAutoScript 碧蓝航线脚本快速指南4 步跑通日常任务托管与大世界自动探索下一篇Proxmark3 Standalone 模式完全指南从模式总览到自定义开发实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考