postforward/truenas-freelance-manager

自由职业者项目共享管理

通过简洁的Web界面管理TrueNAS SMB共享文件夹的自由职业者访问权限，专为视频制作团队设计，无需命令行即可向承包商授予特定项目文件夹的访问权限，避免暴露整个共享目录。

!https://img.shields.io/docker/pulls/postforward/truenas-freelance-manager !https://img.shields.io/docker/image-size/postforward/truenas-freelance-manager/latest

镜像概述

这是一个轻量级Docker应用，可与TrueNAS服务器配合使用，提供简单的管理面板来管理按文件夹划分的SMB访问权限。选择用户、勾选所需文件夹、点击应用即可完成操作，无需命令行。

适用于TrueNAS Scale 25.10+（Goldeye）

核心功能

• 按文件夹访问控制：通过复选框授予或撤销对单个项目文件夹的访问权限
• 用户管理：创建、编辑、锁定和删除TrueNAS SMB用户
• 批量应用：一次性更改多个文件夹权限，带有实时进度指示器
• 应用设置：上传logo、自定义应用名称、管理隐藏用户（均通过UI操作）
• 会话认证：使用httponly cookies进行安全登录（密码仅发送一次，不随每次请求传递）
• WebSocket API：通过WebSocket使用TrueNAS JSON-RPC 2.0（查询耗时约17ms，适配26.04版本）
• 智能缓存：5分钟服务器端访问缓存，页面加载即时，变更时自动失效
• 深色主题：基于Tailwind CSS和Outfit字体构建的简洁深色UI
• 无数据库：所有配置存储在单个JSON文件中，权限通过TrueNAS NFS4 ACL管理

使用场景

适用于视频制作团队，需要向自由职业者/承包商授予特定项目文件夹的访问权限，同时避免暴露整个共享目录，确保数据安全和访问管控效率。

配置说明

1. 创建TrueNAS API密钥

在TrueNAS Web UI中：

1. 进入凭据 > API密钥
2. 点击添加
3. 命名为freelance-project-shares
4. 复制生成的密钥

2. Docker部署

bash
docker run -d \
  --name freelance-project-shares \
  --restart unless-stopped \
  -p 9090:8080 \
  -v /path/to/config:/app/config \
  -e TRUENAS_URL=https://YOUR_TRUENAS_IP \
  -e TRUENAS_API_KEY=YOUR_API_KEY \
  -e SHARE_PATH=/mnt/your-pool/your-share \
  -e APP_PASSWORD=YourSecureAdminPassword \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  postforward/truenas-freelance-manager:latest

然后在浏览器中打开http://YOUR_TRUENAS_IP:9090。

3. TrueNAS自定义应用部署

在TrueNAS UI中：

1. 进入应用 > 发现 > 自定义应用
2. 配置：
   • 镜像：postforward/truenas-freelance-manager:latest
   • 端口：主机9090 -> 容器8080
3. 添加环境变量：

4. （可选）添加存储挂载以持久化设置：

   • 主机：/mnt/dataset/apps/freelance-config（或类似路径）
   • 容器：/app/config

5. 点击安装

环境变量说明

应用设置

点击右上角齿轮图标自定义：

• 应用名称和副标题
• 公司名称（无logo时显示首字母）
• Logo上传（PNG/SVG，最大2MB）
• 强调色选择器
• 隐藏用户（侧边栏排除的系统账户）

设置存储在/app/config/config.json中，挂载该目录可在容器重建时保留设置。

安全说明

• 镜像无敏感信息：所有凭据通过环境变量传递
• 会话cookie：httponly、samesite=strict，24小时过期
• 自动重连：WebSocket在连接中断时自动重连
• 自动重新登录：前端在会话过期时自动重新认证
• 仅局域网使用：设计用于本地网络，远程访问需通过反向代理添加HTTPS

更新方法

bash
docker pull postforward/truenas-freelance-manager:latest
docker restart freelance-project-shares

或从TrueNAS应用UI重启。

故障排除

"SMB用户可能无法配置，因为SMB服务后端未初始化"

• SMB服务必须运行，从TrueNAS UI > 系统 > 服务启动。

用户更改权限后仍能访问受限文件夹

• SMB缓存权限，用户需断开并重新连接共享：
  Windows：通过文件资源管理器断开映射驱动器，再重新映射\\server\share。

日志中出现500错误/管道破裂

• 与TrueNAS的WebSocket连接超时，应用会在下次请求时自动重连。

技术栈

• 运行时：Python 3.12、FastAPI、websocket-client
• 前端：Tailwind CSS v4、Outfit字体、单页深色UI
• API：TrueNAS JSON-RPC 2.0 over WebSocket（适配TrueNAS 26.04）
• 镜像：约50MB（基于python:3.12-slim），多架构（amd64 + arm64）

许可证

MIT

---

由PostForward开发，用于视频制作存储基础设施的自由职业者访问管理。