# tafile **Repository Path**: goodtim/tafile ## Basic Information - **Project Name**: tafile - **Description**: 用于windows/linux快速创建一个WEB文件管理的软件。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-04 - **Last Updated**: 2026-02-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 文件管理器 一个简单易用的文件管理器，基于 Go 语言开发，支持文件上传、下载、重命名、创建目录等功能，同时具有路径遍历攻击防护和完整的 API 接口。 ## 功能特性 - ✅ 文件上传：支持多文件批量上传 - ✅ 文件下载：直接点击文件即可下载 - ✅ 文件重命名：支持修改文件名称 - ✅ 文件删除：支持删除文件和目录 - ✅ 目录浏览：支持多级目录浏览 - ✅ 创建目录：支持在当前目录创建新目录 - ✅ 图片预览：支持图片文件的缩略图预览 - ✅ 路径防护：防止路径遍历攻击，确保文件安全 - ✅ 响应式设计：适配不同屏幕尺寸 - ✅ Windows 服务支持：可作为 Windows 服务运行，支持自动启动 - ✅ 配置化：支持自定义服务名和网站名 - ✅ API 接口：完整的 RESTful API 接口，支持登录、获取文件列表、搜索文件、下载文件、生成签名、上传文件、删除文件等功能 - ✅ API 测试页面：提供可视化的 API 测试工具，方便调试和使用 - ✅ 认证机制：支持 Bearer Token 认证和 HMAC-SHA256 签名验证 - ✅ 压缩包生成：支持一键生成 Linux 和 Windows 版本的压缩包 ## 系统界面 ### 登录界面 ![登录界面](docs/images/登录界面.png) ### 文件列表 ![文件列表](docs/images/文件列表.png) ### 2FA设置页 #### 未启用2FA ![2FA设置页-未启用2FA](docs/images/2FA设置页-未启用2FA.png) #### 已启用2FA ![2FA设置页-已启用2FA](docs/images/2FA设置页-已启用2FA.png) ### 推荐认证器 ![腾讯身份认证器](docs/images/腾讯身份认证器.png) ## 技术栈 - **后端**：Go 语言，标准库 `net/http` 处理 HTTP 请求 - **前端**：HTML5 + CSS3 + JavaScript - **模板**：Go 标准库 `text/template` - **图片处理**：`github.com/disintegration/imaging` 用于生成缩略图 - **Windows 服务**：`golang.org/x/sys/windows/svc` 用于实现 Windows 服务支持 ## 版本历史 ### v1.1.0 - ✅ 新增删除文件/目录 API 接口：支持通过 API 删除文件和目录 - ✅ 新增上传文件 API 接口：支持通过 API 上传文件，支持自定义文件名 - ✅ 优化登录接口：返回的用户信息不包含密码，提高安全性 - ✅ 完善 API 测试页面：添加删除和上传接口的测试功能 - ✅ 更新 API 文档：添加删除和上传接口的详细说明 ### v1.0.0 - ✅ 初始版本发布 - ✅ 基本文件管理功能（上传、下载、重命名、创建目录） - ✅ 图片预览功能 - ✅ Windows 服务支持 - ✅ 路径遍历防护 - ✅ 完整的 RESTful API 接口 - ✅ API 测试页面 - ✅ Bearer Token 认证 - ✅ 下载文件签名验证 - ✅ 压缩包生成功能 - ✅ 新增配置项 `api_enable` 和 `download_overtime` ## 使用方法 ### 1. 访问文件管理器 打开浏览器，访问 `http://localhost:9080` 即可进入文件管理器。 ### 2. 上传文件 点击页面顶部的 "上传文件" 按钮，选择要上传的文件，然后点击 "上传文件" 按钮即可。 ### 3. 下载文件 直接点击文件列表中的文件即可下载。 ### 4. 重命名文件 点击文件列表中文件右侧的 "重命名" 链接，修改文件名后点击 "确认" 按钮即可。 ### 5. 创建目录 点击页面顶部的 "创建目录" 按钮，输入目录名称后点击 "确认" 按钮即可。 ### 6. 浏览目录 点击文件列表中的目录即可进入子目录，点击导航栏中的 "根目录" 或其他目录名称即可返回对应目录。 ## 使用指南 ### 小白用户指南 1. **下载程序** - 从发布页下载适合您系统的压缩包： - Windows 用户：下载 `tafile-windows-amd64.zip` - Linux 用户：下载 `tafile-linux-amd64.tar.gz` 2. **解压文件** - Windows 用户：右键点击 zip 文件，选择 "解压到当前文件夹" - Linux 用户：使用命令 `tar -xzf tafile-linux-amd64.tar.gz` 解压 3. **首次运行** - Windows 用户：双击 `tafile.exe` 文件 - Linux 用户：在终端中运行 `./tafile` - 程序会自动创建 `config.yaml` 配置文件 4. **简单配置**（可选） - 用记事本打开 `config.yaml` 文件 - 主要修改以下内容： - `port`：服务端口，默认为 9080 - `root_dir`：文件存放目录，默认为 `./files` - `site_name`：网站名称，默认为 "文件管理器" - 修改配置后，需要重启程序才能生效 5. **访问网站** - 打开浏览器，访问 `http://localhost:9080` - 您将看到文件管理器的主界面 6. **开始使用** - 上传文件：点击 "上传文件" 按钮，选择要上传的文件 - 下载文件：直接点击文件列表中的文件 - 创建目录：点击 "创建目录" 按钮，输入目录名称 - 重命名文件：点击文件右侧的 "重命名" 链接 7. **API 测试**（可选） - 在页面顶部点击 "API 测试" 链接 - 您可以在这里测试各种 API 接口功能 8. **常见问题** - **无法访问网站**：检查端口是否被占用，或防火墙是否阻止 - **上传失败**：检查文件大小是否超过限制，或文件类型是否被允许 - **下载文件乱码**：这是正常现象，文件内容不会受影响 - **程序闪退**：检查根目录是否存在且有读写权限 9. **停止程序** - Windows 用户：关闭命令窗口或任务管理器结束进程 - Linux 用户：在终端中按 `Ctrl+C` ### 进阶用户指南 1. **Windows 服务安装** - 以管理员身份运行命令提示符 - 进入程序所在目录 - 执行安装命令：`tafile.exe -install` - 服务将被设置为自动启动，系统启动时会自动运行 2. **Windows 服务管理** - 启动服务：`sc start FileManagerService` - 停止服务：`sc stop FileManagerService` - 查看服务状态：`sc query FileManagerService` 3. **配置文件管理** - 配置文件位置：程序运行目录下的 `config.yaml` - 修改配置后需要重启服务才能生效 - 建议在修改配置前备份原文件 4. **常用使用场景** - **家庭文件共享**： - 设置 `root_dir` 为家庭共享目录 - 配置 `auth_enable: true` 启用认证 - 添加家庭成员为用户 - **公司内部文件管理**： - 设置 `root_dir` 为公司共享目录 - 配置 `auth_enable: true` 启用认证 - 限制 `allowed_exts` 仅允许办公文件类型 - 启用 `api_enable: true` 供其他系统集成 - **个人云盘**： - 设置 `root_dir` 为个人云盘目录 - 配置 `auth_enable: true` 启用认证 - 设置 `api_enable: true` 支持多设备访问 5. **服务卸载** - 以管理员身份运行命令提示符 - 执行卸载命令：`tafile.exe -uninstall` - 服务将被完全移除 ### 开发者指南 1. **构建项目** - 克隆代码：`git clone https://github.com/yourusername/file-manager.git` - 进入目录：`cd file-manager` - 安装依赖：`go mod tidy` - 构建项目：`make`（会自动编译并生成压缩包） 2. **自定义配置** - 编辑 `config.yaml` 文件，根据需要修改配置项 - 重点关注： - `root_dir`：文件管理器的根目录 - `port`：服务监听的端口 - `users`：用户列表配置 - `api_enable`：是否启用 API 接口 - `download_overtime`：下载签名有效期 - `allowed_exts`：允许上传的文件扩展名 - `auth_enable`：是否启用认证 - `secret_key`：会话令牌密钥（生产环境务必设置） ### 2FA使用指南 #### 什么是2FA 2FA（双因素认证）是一种安全机制，要求用户在登录时提供两种不同类型的验证信息： - 第一因素：用户名和密码（你知道的信息） - 第二因素：一次性验证码（你拥有的设备生成的信息） 2FA可以大大提高账户的安全性，即使密码被泄露，攻击者也无法登录你的账户。 #### 如何启用2FA 1. **登录系统**：使用你的用户名和密码登录文件管理器 2. **访问2FA设置**：在页面顶部导航栏中找到并点击"2FA设置"链接 3. **启用2FA**：在2FA设置页面中，点击"启用2FA"按钮 4. **扫描二维码**：使用认证器应用扫描页面上显示的二维码 5. **验证验证码**：在认证器应用中获取6位验证码，输入到验证框中，然后点击"验证验证码"按钮 6. **完成设置**：验证成功后，2FA就已经启用了 #### 如何使用2FA进行登录 1. **打开登录页面**：访问 `http://localhost:9080/login` 2. **输入用户名和密码**：在登录表单中输入你的用户名和密码 3. **输入2FA验证码**：打开认证器应用，获取当前的6位验证码，输入到"2FA验证码"字段中 4. **点击登录**：点击"登录"按钮完成登录 #### 推荐的认证器应用 - **腾讯身份认证器**：在微信中搜索小程序 - **其他支持TOTP协议的认证器应用** #### 常见问题和解决方案 1. **无法扫描二维码** - 确保你的认证器应用已更新到最新版本 - 确保摄像头清晰，没有遮挡 - 如果二维码无法扫描，可以手动输入密钥到认证器应用 2. **验证码不正确** - 确保输入的是认证器应用中当前显示的验证码（每30秒更新一次） - 确保你的设备时间与网络时间同步 - 如果你多次输入错误，可能需要重新设置2FA 3. **丢失了认证器设备** - 如果你丢失了认证器设备，你将无法使用2FA验证码登录 - 解决方案：在config.yaml中禁用2FA，然后重新启用 4. **如何禁用2FA** - 登录系统后，访问2FA设置页面 - 点击"禁用2FA"按钮 - 确认禁用操作 #### 安全提示 - **保存恢复密钥**：在config.yaml中配置`auth_enable: false`，禁用2FA后,重启服务生效，然后按照正常登录流程进行登录，然后重新启用2FA，和扫码即可。 - **定期测试**：定期测试2FA登录，确保一切正常工作 - **保持设备安全**：如果设备丢失，建议禁用2FA，然后在config.yaml中配置`auth_enable: false`，并删除`auth_secret_key`，重启服务会自动生成新的 `auth_secret_key`，然后按照正常登录流程进行登录，然后重新启用2FA，和扫码即可。 3. **API 接口使用** - 访问 API 测试页面：`http://localhost:9080/api-test` - API 测试页面提供了所有接口的可视化测试工具 - 每个接口都有详细的参数说明和响应示例 - 支持直接在页面上测试所有 API 接口 4. **高级构建选项** - 使用 UPX 压缩：`make USE_UPX=true` - 仅构建 Linux 版本：`make linux` - 仅构建 Windows 版本：`make windows` - 仅生成压缩包：`make package` 5. **部署建议** - **生产环境**： - 启用认证：设置 `auth_enable: true` - 配置强密码：修改 `users` 列表中的密码 - 设置 `secret_key`：为会话令牌设置安全的密钥 - 配置防火墙：仅允许必要的端口访问 - **反向代理**： - 可使用 Nginx 或 Apache 作为反向代理 - 配置 HTTPS 以增强安全性 - **容器化部署**： - 可使用 Docker 容器化部署 - 示例 Dockerfile： ```dockerfile FROM golang:1.20-alpine AS builder WORKDIR /app COPY . . RUN apk add --no-cache make tar zip RUN make linux FROM alpine:latest WORKDIR /app COPY --from=builder /app/dist/tafile-linux-amd64 /app/tafile COPY config.yaml /app/ RUN chmod +x /app/tafile EXPOSE 9080 CMD ["/app/tafile"] ``` 6. **API 响应格式** - 所有 API 接口均返回统一的 JSON 格式： ```json { "code": 200, // 状态码，200 表示成功 "message": "成功", // 状态消息 "data": {} // 响应数据，根据接口不同而不同 } ``` - 错误响应示例： ```json { "code": 401, // 状态码，表示未授权 "message": "未授权", // 错误消息 "data": null // 错误时 data 为 null } ``` ## 安全特性 - **路径遍历防护**：系统会验证所有路径是否在根目录内，防止路径遍历攻击 - **文件类型限制**：可在配置文件中设置允许上传的文件扩展名 - **认证机制**：可在配置文件中启用认证，设置用户名和密码 ## 目录结构 ``` tafile/ ├── src/ # 源代码目录 │ ├── tpl/ # 模板文件目录 │ │ ├── api_test_page.go # API 测试页面模板 │ │ ├── file.go # 文件管理页面模板 │ │ ├── login.go # 登录和2FA设置页面模板 │ │ └── search.go # 搜索结果页面模板 │ ├── api.go # API 接口相关代码 │ ├── auth.go # 认证相关代码 │ ├── config.go # 配置相关代码 │ ├── files.go # 核心功能代码 │ ├── go.mod # 依赖管理文件 │ ├── go.sum # 依赖校验文件 │ ├── main.go # 主入口文件 │ ├── service_nonwindows.go # 非Windows服务支持 │ └── windows_service.go # Windows服务支持 ├── docs/ # 文档目录 │ └── images/ # 系统界面截图 ├── .gitignore # Git忽略文件 ├── COMPRESSION.md # 压缩相关文档 ├── LICENSE # MIT许可证文件 ├── Makefile # 构建脚本 ├── README.md # 本文档 ├── config.yaml.example # 配置文件示例 └── go.mod # 依赖管理文件 ``` ## 配置说明 ### 端口配置 `port` 字段设置服务监听的端口，默认为 9080。 ### 根目录配置 `root_dir` 字段设置文件管理器的根目录，所有文件操作都将在此目录内进行。 ### 文件类型限制 `allowed_exts` 字段设置允许上传的文件扩展名，空数组表示允许所有文件类型。 ### 认证配置 `auth_enable` 字段设置是否启用认证，默认为 false。 `users` 字段设置用户列表，包含用户名、密码和是否为管理员的标识。这些用户可用于登录网站和获取 API 接口的 Bearer Token。 ### 2FA 配置 `two_fa_enable` 字段设置是否启用双因素认证，默认为 false。 `two_fa_key` 字段设置 2FA 密钥，用于生成和验证一次性验证码。 ### 会话配置 `secret_key` 字段设置会话令牌密钥，用于加密会话数据。生产环境中务必设置为强密钥。 ### 服务配置 `service_name` 字段设置 Windows 服务名称，默认为 "FileManagerService"。 ### 网站配置 `site_name` 字段设置网站名称，将显示在页面标题和首页，默认为 "文件管理器"。 ### API 配置 `api_enable` 字段设置是否启用 API 接口，默认为 true。当设置为 false 时，API 接口将被禁用，页面上的 API 测试链接也不会显示。 `download_overtime` 字段设置下载文件接口签名的有效秒数，默认为 3600 秒（1 小时）。 ## 注意事项 1. 确保根目录存在且具有读写权限 2. 如需更改根目录，修改配置文件中的 `root_dir` 字段即可 3. 生产环境建议启用认证，设置强密码 4. 定期备份重要文件，以防意外丢失 5. 安装和卸载 Windows 服务需要以管理员身份运行命令 6. 服务默认以 `LocalSystem` 身份运行，具有足够的权限访问系统资源 7. 服务启动时会自动加载配置文件，并验证配置的有效性 8. 如果配置文件中的根目录不存在，服务会启动失败并记录错误日志 ## 许可证 本项目采用 MIT 许可证，详见 LICENSE 文件。 ## 贡献 欢迎提交 Issue 和 Pull Request，帮助改进本项目。 ## 联系方式 如有问题或建议，可通过以下方式联系： - GitHub：[https://gitee.com/goodtim/tafile](https://gitee.com/goodtim/tafile) - Email：bkkkd@163.com --- **享受使用文件管理器！** 🎉