从零搭建轻量跨平台开源档案管理系统Teedy 全步骤指南

前期准备：确保3个跨平台基础条件

本次使用Teedy（原Silex，文档协作与档案管理兼顾的轻量Java项目），以下3个是跨平台通用的前置要求，Windows、macOS、Linux操作完全一致：

• 安装Docker Desktop（社区版）：Windows/macOS直接去官网下载安装包，地址为https://www.docker.com/get-started/；Linux（Ubuntu示例）执行以下命令：

```bash 更新软件源 sudo apt update 安装Docker依赖 sudo apt install ca-certificates curl gnupg lsb-release 添加Docker官方GPG密钥 sudo mkdir -m 0755 -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg 设置Docker稳定版软件源 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null 再次更新并安装Docker Desktop组件 sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ```

• 确保Docker Desktop处于运行状态：Windows/macOS点击启动图标；Linux执行sudo systemctl start docker && sudo systemctl enable docker
• 准备1个本地文件夹：用于存放档案数据（图片、PDF、元数据等），避免容器重启后数据丢失，Windows示例路径：D:\teedy_data；macOS示例：/Users/你的用户名/teedy_data；Linux示例：/home/你的用户名/teedy_data

核心操作：1条命令启动跨平台Teedy服务

这里使用官方维护的Docker Compose单文件配置，无需手动写复杂配置，可直接复制粘贴使用：

步骤1：创建docker-compose.yml文件

在桌面或任意易访问的位置新建文本文件，重命名为docker-compose.yml（注意后缀名必须是.yml，Windows系统需先开启“显示文件扩展名”功能，避免隐藏成.txt），然后将以下完整配置内容粘贴进去：

```yaml version: '3.8' services: teedy: image: teedyio/teedy:latest container_name: teedy restart: unless-stopped ports: - "8080:8080" volumes: 替换下方路径为你本地准备的文件夹路径！ - "D:/teedy_data:/data" environment: 配置初始管理员账号密码（首次登录后立即修改） - TEEDY_USERNAME=admin - TEEDY_PASSWORD=admin123456 配置时区为中国标准时间（跨平台通用，解决上传/归档时间错乱问题） - TZ=Asia/Shanghai ```

• 特别注意：volumes下的路径必须按你本地实际修改，Windows用/代替\，前后引号保留；如果你的8080端口被占用，可把左边的8080改成其他未占用端口（比如8081:8080）

步骤2：启动Teedy服务

打开终端（Windows用PowerShell或CMD，macOS/Linux用Terminal），进入docker-compose.yml文件所在的目录：

• Windows示例（假设文件在桌面）：cd C:\Users\你的用户名\Desktop
• macOS示例：cd /Users/你的用户名/Desktop
• Linux示例：cd /home/你的用户名/Desktop

然后执行以下启动命令：

```bash docker-compose up -d ```

首次执行会自动从Docker Hub拉取Teedy的最新镜像（约200MB，根据网速等待1-5分钟），看到类似“Creating teedy ... done”的提示后服务启动成功。

落地使用：4步完成基础档案管理配置

步骤1：登录Teedy后台

打开任意浏览器（Chrome、Edge、Safari、Firefox通用），访问地址：http://localhost:8080（如果改了端口就用对应端口），输入配置文件里的初始账号admin、密码admin123456登录。

步骤2：修改初始管理员密码

登录后点击右上角的用户名（admin）→设置→账户，输入原密码和新密码（新密码建议至少8位，包含数字和字母），点击保存，刷新页面重新登录。

步骤3：创建档案分类（必填，否则无法上传档案）

点击左侧菜单的管理→分类，点击右上角的新建分类，填写以下必填信息：

• 名称：比如“财务档案”“人事档案”“项目文档”
• 权限：勾选“查看者”“上传者”等默认组的权限（如果是个人用，全选即可）

填写后点击保存，可重复此步骤创建多个分类。

步骤4：上传并管理第一份档案

点击左侧菜单的档案→新建档案，按以下步骤操作：

• 上传文件：点击“选择文件”按钮，或直接拖拽PDF、图片、Word、Excel等文件到上传区域
• 选择分类：在右侧“分类”下拉框中选择刚才创建的分类
• 补充元数据（可选但推荐）：填写档案标题、描述、创建日期、标签等信息，方便后续检索
• 保存档案：点击右上角的保存按钮

保存后可在左侧菜单的档案中查看、搜索、编辑、下载或分享档案。

跨平台验证：3个设备快速同步

Teedy是基于Web的服务，同一局域网内的所有设备（手机、平板、另一台电脑）都可以访问：

• 获取本机局域网IP：Windows执行ipconfig，找到“无线局域网适配器WLAN”或“以太网适配器以太网”的IPv4地址（比如192.168.1.100）；macOS执行ifconfig，找到“en0”或“en1”的inet地址；Linux执行ifconfig或ip addr
• 关闭本机防火墙的8080端口限制：Windows防火墙→高级设置→入站规则→新建规则→端口→TCP→特定本地端口8080→允许连接→全选→命名为Teedy→保存；macOS/Linux个人用户一般无需关闭，企业用户需开放对应端口
• 其他设备访问：同一局域网内的设备打开浏览器，访问http://本机局域网IP:8080，用刚才修改后的管理员账号或后续创建的普通账号登录，即可同步查看和管理档案。

常见卡壳问题解决

• Docker拉取镜像失败：在Docker Desktop的设置→Docker Engine中添加国内镜像源，保存后重启Docker，镜像源配置如下：

```json { "registry-mirrors": [ "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com" ] } ```

• 本地文件夹权限不足（macOS/Linux常见）：在终端执行sudo chmod -R 777 你的本地文件夹路径（比如sudo chmod -R 777 /Users/你的用户名/teedy_data）
• 上传大文件失败：在docker-compose.yml文件的environment部分添加一行- TEEDY_MAX_UPLOAD_SIZE=100M（可改成1G、2G等，注意单位是M或G），然后执行docker-compose down && docker-compose up -d重启服务