# LAN Share

**Repository Path**: jumperck/lan-share

## Basic Information

- **Project Name**: LAN Share
- **Description**: 轻量级局域网文件与文字共享工具。Docker 一键部署，免登录，打开浏览器即用。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: networklib

**Tags**: None

## README

# LAN Share — 局域网文件与文字共享工具

轻量级局域网文件与文字共享工具。Docker 一键部署，免登录，打开浏览器即用。

## 功能

- 📁 文件共享：拖拽上传、**文件夹上传（保留目录结构）**、原地替换、一键下载和删除
- 🌐 页面预览：上传单文件 `.html` / `.md`，生成链接在浏览器内直接打开
- 🤖 MCP 集成：AI 工具通过 `/mcp` 远端上传与管理文件
- 📋 文字共享：粘贴保存、一键复制到剪贴板
- 🔓 免登录：无需注册，打开即用
- 📱 响应式：适配桌面和移动端

## 快速开始

```bash
git clone git@gitee.com:jumperck/lan-share.git
cd lan-share
./start.sh
```

启动后终端会输出访问地址，包括本机和局域网地址。

默认端口为 `3333`，如需修改请编辑 `docker-compose.yml` 中的 `ports` 配置：

```yaml
ports:
  - "你的端口:3333"   # 冒号左边改成你想要的端口
```

## 更新部署

```bash
git pull
./start.sh
```

会自动重新构建并重启，已上传的文件和文字数据不受影响。

## 文件夹上传与路径唯一

支持选择或拖拽整个文件夹上传，文件在列表中按 **逻辑路径** 展示（如 `site/css/app.css`）。存储采用扁平落盘 + 路径维护层级（类似 OSS object key）。

- **路径唯一**：同一路径默认不能重复上传；Web 端会提示是否替换
- **强制覆盖**：API 使用 `?force=true`，MCP 使用 `force: true`；覆盖后 **file_id 与预览链接不变**
- **单批限制**：最多 200 个文件，单文件最大 100 MB，单批总大小最大 500 MB
- **列表筛选**：`GET /api/files?prefix=site/` 可按路径前缀过滤

> **预览说明**：文件夹内各文件可单独预览/下载，但 HTML 页面中的相对路径资源（如 `./style.css`）仍无法加载；外链 CDN 资源可正常使用。

## Docker 镜像加速

若执行 `./start.sh` 时出现无法拉取 `node:20-alpine`、`context deadline exceeded` 等错误，通常是访问 Docker Hub 超时。可配置镜像加速后重试：

1. 打开 **Docker Desktop → Settings → Docker Engine**
2. 在 JSON 配置中加入 `registry-mirrors`（保留原有其他配置项）：

```json
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ]
}
```

3. 点击 **Apply & restart** 重启 Docker
4. 重新执行 `./start.sh`

## 页面预览

上传 **单文件** `.html`、`.htm` 或 `.md` 后，可在浏览器内直接预览，无需下载。

### 使用方式

1. 在「文件共享」区域上传 HTML 或 Markdown 文件
2. 文件列表中会出现 **打开预览** 和 **复制链接** 按钮
3. 需要更新文件内容时，点击 **替换** 选择新文件；`file_id` 与预览链接保持不变
4. 分享链接格式：`http://{地址}:{端口}/view/{文件ID}`

### 支持范围

| 类型 | 行为 |
|------|------|
| `.html` / `.htm` | 浏览器内联渲染原始页面 |
| `.md` | 服务端渲染为带样式的 HTML 页面 |
| 其他格式 | 不支持预览，仍可正常下载 |

> **说明**：当前仅支持单文件页面。HTML 中的相对路径资源（如 `./style.css`）无法加载；外链 CDN 资源可正常使用。

### 示例页面

项目内置了一份基于本 README 的展示页，可直接上传体验：

```
examples/lan-share-showcase.html
```

## MCP 集成

Docker 一键部署后，MCP 端点随服务自动开放，AI 工具（如 Cursor）可通过局域网 URL 远程上传与管理文件。

### 接入地址

`./start.sh` 启动成功后会输出：

```
MCP 接入:   http://10.10.150.140:3333/mcp
```

本地开发时地址为 `http://localhost:3333/mcp`。

### Cursor 配置

在 Cursor 的 MCP 设置中添加（将 IP 替换为服务器局域网地址）：

```json
{
  "mcpServers": {
    "lan-share": {
      "url": "http://10.10.150.140:3333/mcp"
    }
  }
}
```

### 可用工具

| 工具 | 说明 |
|------|------|
| `lan_share_upload_file` | 创建或覆盖文件（`filename` 为逻辑路径，可含目录；`content`；可选 `encoding`、`force`） |
| `lan_share_update_file` | **原地更新**已有文件（`file_id` + `content`，可选 `encoding`）；path 与预览链接不变 |
| `lan_share_read_file` | 读取文件内容（`file_id`，可选 `encoding`）；返回含 `path` |
| `lan_share_list_files` | 列出所有文件 |
| `lan_share_get_file` | 获取文件元信息与完整预览链接（不含内容） |
| `lan_share_delete_file` | 删除文件（`file_id`） |

### AI 跟踪更新工作流

AI 可通过稳定的 `file_id` 反复读写同一文件，预览链接 `/view/{file_id}` 始终不变：

1. `lan_share_upload_file` → 保存返回的 `id` 与 `full_preview_url`（`filename` 可用 `docs/page.html`）
2. 需要修改时：`lan_share_read_file` → 编辑内容 → `lan_share_update_file`（传入同一 `file_id`）
3. 同路径再次上传需 `force: true`，否则工具会报错
4. 浏览器访问 `full_preview_url` 即可查看最新内容

### 环境变量

| 变量 | 说明 |
|------|------|
| `PUBLIC_BASE_URL` | 生成预览链接的公网/局域网基址，如 `http://10.10.150.140:3333`。`start.sh` 会自动写入 `.env` |

> **安全提示**：当前 MCP 与 API 均无鉴权，仅建议在可信局域网内使用。

首页也会显示 MCP 接入地址与 Cursor 配置，可直接复制。

## 数据持久化

数据通过 Docker Volume 自动持久化，容器重建不丢失。

如需挂载到宿主机目录，编辑 `docker-compose.yml`：

```yaml
volumes:
  - /your/path:/app/data   # 替换为宿主机目录
```

## 本地开发

```bash
# 后端（端口 3333）
npm install && npm start

# 前端（端口 5173，需另开终端）
cd client && npm install && npm run dev

# 测试
npm test              # 后端
cd client && npm test # 前端
```

开发模式下前后端分离运行：

- 管理界面访问 `http://localhost:5173`
- Vite 会将 `/api` 和 `/view` 代理到后端 `http://localhost:3333`
- 预览链接也可直接访问 `http://localhost:3333/view/{文件ID}`
- MCP 端点：`http://localhost:3333/mcp`（AI 工具直连后端，无需 Vite 代理）

修改 `client/vite.config.js` 中的 proxy 配置后，需重启 Vite 开发服务器。

## 技术栈

Node.js + Express / Vue 3 + Vite / MCP Streamable HTTP / marked（Markdown 渲染）/ 文件系统 + JSON 存储 / Docker 多阶段构建