零门槛可复用技术开发档案管理软件从零搭建落地实操全指南

一、前置环境准备

1.1 硬件要求

最低配置：2核4G云服务器/本地主机，操作系统支持CentOS7+、Ubuntu20.04+，如需外网访问需提前配置公网IP并开放3000端口。

1.2 依赖安装

本方案基于Docker容器化部署，无额外依赖，直接执行对应系统的安装命令即可：

``` Ubuntu20.04+ 执行 sudo apt update && sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker CentOS7+ 执行 sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl enable --now docker ```

安装完成后执行docker -v、docker compose version验证版本，Docker Compose版本需≥2.10.0。

二、软件部署实操

2.1 拉取并修改配置文件

执行以下命令创建工作目录：

``` mkdir -p /data/dev-doc && cd /data/dev-doc ```

在该目录下新建docker-compose.yml文件，完整内容如下，可直接复制使用：

``` version: '3.8' services: postgres: image: postgres:14-alpine restart: always environment: POSTGRES_DB: dev_archive POSTGRES_USER: dev_archive POSTGRES_PASSWORD: Dev@Archive2024 可自定义数据库密码 volumes: - ./postgres:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U dev_archive"] interval: 5s timeout: 5s retries: 5 app: image: docmost/docmost:latest restart: always depends_on: postgres: condition: service_healthy environment: APP_URL: http://你的服务器IP:3000 替换为你的实际访问地址 APP_SECRET: 替换为32位随机字符串，可执行openssl rand -hex 16生成 DB_URL: postgresql://dev_archive:Dev@Archive2024@postgres:5432/dev_archive MAIL_FROM: no-reply@yourdomain.com 无需邮件通知可保持默认 ports: - "3000:3000" 左侧端口可自定义，避免冲突即可 volumes: - ./storage:/app/storage ```

必须修改的配置项：APP_URL替换为你的实际访问地址，APP_SECRET替换为随机生成的32位字符串，数据库密码可按需修改，修改后需同步修改DB_URL中的密码字段。

2.2 启动服务

配置文件修改完成后，执行以下命令启动服务：

``` docker compose up -d ```

启动后执行docker compose logs -f app查看启动日志，出现「Server running on port 3000」即为启动成功，访问http://你的IP:3000即可进入登录页，默认管理员账号：admin@admin.com，默认密码：changeme，首次登录必须修改密码。

三、技术开发档案场景适配配置

3.1 自定义档案分类

登录后台后进入【空间设置】-【分类管理】，必须添加4类核心分类：需求文档库、技术设计库、迭代版本库、故障复盘库，每个分类单独配置权限：开发组可编辑，产品/测试组只读，管理层仅可见概览，避免非授权人员修改核心档案。

3.2 配置上传校验规则

进入【系统设置】-【上传规则】，开启以下强制规则：

• 命名规范校验：规则配置为[分类]-[日期]-[负责人]-[文件名]，例：技术设计-20240520-张三-用户中心接口设计，不符合命名规则的文件直接拦截并提示修改
• 格式限制：仅允许上传.md/.pdf/.docx/.zip/.png格式文件，禁止可执行文件上传
• 版本自动留存：开启后每次修改档案自动生成版本号，最多可回溯100个历史版本，支持任意版本对比和回滚

3.3 关联代码仓库Webhook

进入【集成设置】-【Webhook】，新增Gitlab/Github钩子，触发地址填写http://你的服务地址/api/webhook/git，触发事件选择【代码合并请求】，配置完成后每次代码合并会自动关联对应迭代版本库的档案，同步commit记录到档案备注。可执行以下命令测试配置是否生效：

``` curl -X POST http://你的服务地址/api/webhook/git \ -H "Content-Type: application/json" \ -d '{"project":"user-center","commit_id":"a1b2c3d","version":"v1.2.0","author":"张三"}' ```

返回{"code":200,"msg":"success"}即为配置成功。

四、日常使用操作指南

4.1 档案上传

普通用户登录后进入对应分类，点击【上传/新建】，必须填写元数据：关联迭代ID、关联需求ID、负责人联系方式、生效时间，提交后系统自动校验命名规范和格式，校验通过即可归档，校验失败会给出具体修改提示。

4.2 档案检索

顶部搜索框输入关键词即可检索，支持全量模糊检索、分类筛选、时间范围筛选、负责人筛选，上传的.md文件中的代码片段会自动提取索引，支持代码片段检索，响应时间≤1秒。

4.3 权限调整

管理员进入【成员管理】可按角色分配权限：访客：仅可检索查看；开发者：可上传编辑自己负责的档案；超级管理员：可修改所有档案、调整权限、导出全量档案。

五、运维与备份配置

5.1 常见故障排查

• 服务无法启动：执行docker compose ps查看异常容器，大概率是3000端口被占用，修改docker-compose.yml中ports字段的左侧端口即可
• 上传文件失败：执行df -h查看磁盘使用率，超过90%时进入【系统设置】-【缓存管理】清理7天前的历史版本缓存即可
• 检索无结果：执行docker compose exec app npm run scout:import重建索引，5分钟后即可正常检索

5.2 自动备份配置

执行crontab -e添加以下定时任务，实现自动备份和过期备份清理：

``` 每日凌晨2点全量备份数据库和档案文件 0 2 mkdir -p /data/backup 0 2 cd /data/dev-doc && docker compose exec -T postgres pg_dump -U dev_archive dev_archive > /data/backup/db_$(date +\%Y\%m\%d).sql 0 2 tar -zcf /data/backup/file_$(date +\%Y\%m\%d).tar.gz /data/dev-doc/storage 自动删除7天前的备份 0 3 find /data/backup -mtime +7 -name ".sql" -o -name ".tar.gz" -delete ```

恢复方法：停止服务后，执行psql -U dev_archive dev_archive < 备份sql文件导入数据库，解压文件备份覆盖./storage目录，重启服务即可完成恢复。

六、落地验证标准

完成以上配置后，满足以下4点即为完全落地可用：

• 开发团队成员可正常登录、上传对应分类档案，命名不符合规范直接被拦截
• 输入迭代/需求关键词可1秒内检索到对应所有档案
• 代码仓库合并请求提交后，自动同步记录到对应版本档案
• 每日自动生成备份文件，备份文件可正常恢复数据