HHostingByteSoftware
Ctrl K
ComunidadGuías…

README.zh-CN.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
<div align="center">

<img src="https://raw.githubusercontent.com/SWUFE-DB-Group/TexLite/main/src/client/public/texlite-icon.svg" width="72" height="72" alt="TexLite 标志" />

# TexLite

面向*小型、可信*研究团队的轻量自托管 Overleaf 替代方案。直接使用现有的 LaTeX
发行版和 Coding Agents，无需沉重的服务栈。

[![CI](https://github.com/SWUFE-DB-Group/TexLite/actions/workflows/ci.yml/badge.svg)](https://github.com/SWUFE-DB-Group/TexLite/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/texlite?logo=npm&label=npm)](https://www.npmjs.com/package/texlite)
[![Docker Hub](https://img.shields.io/docker/v/zhongpu/texlite?logo=docker&label=Docker%20Hub)](https://hub.docker.com/r/zhongpu/texlite)

**文档：** [English](README.md) · [运维指南（英文）](OPERATIONS.md) · [设计文档（英文）](DESIGN.md) · 简体中文（当前文件）

**网站：** [TexLite GitHub Pages](https://swufe-db-group.github.io/TexLite/)

</div>

https://github.com/user-attachments/assets/c2b277ab-7cab-4f2b-8684-358fd9fefe8f

## 为什么选择 TexLite

- **掌控写作环境。** 直接使用宿主机 TeX 环境和 Coding Agents，并将源码、历史版本和编译产物保存在
  一个本地数据目录中。
- **无需庞大服务栈即可协作。** 默认部署只有一个 Node.js 进程、SQLite 和本地文件，
  同时提供实时编辑和源码级批注，适合少量可信协作者。

## 快速开始

安装 Node.js 24 或更高版本、`latexmk`，以及至少一个 TeX 引擎，例如 `pdflatex`、
`xelatex` 或 `lualatex`。只有使用可选 Git/GitHub 集成时才需要 Git。

安装后可先执行 `texlite requirements`，检查相关宿主机软件及版本。

```bash
npm install --global texlite
texlite requirements
texlite init
texlite start
texlite status
```

访问 <http://127.0.0.1:3000>。`texlite init` 会创建配置并建立第一个管理员；TexLite
不开放公众注册。
如需把 TexLite 挂载到现有域名的 `/texlite` 等子路径，请设置
`server.basePath`，并参考[反向代理说明（英文）](OPERATIONS.md#reverse-proxy-subpath)。

升级与日常管理：

```bash
npm update --global texlite
texlite restart
texlite logs
```

`texlite serve` 会以前台方式运行，适合调试、Docker 或 systemd。`start`、`stop`、
`restart`、`status`、`logs` 使用 npm 包内置的 PM2 运行时；完整命令请执行
`texlite help`。

## 与 Overleaf 的实际区别

[Overleaf](https://www.overleaf.com/about/features-overview) 在团队需要其托管产品或更完整生态时
仍然是很好的选择。TexLite 面向的是更窄的自托管场景：

- 共享托管服务在使用高峰期可能排队、变慢或出现编译超时。
- Overleaf 开源 [Community Edition](https://github.com/overleaf/overleaf) 的
  [Docker 部署路径](https://docs.overleaf.com/on-premises/getting-started/what-is-the-overleaf-toolkit) 更复杂，且源码批注等高级功能 [仅限 Server Pro](https://docs.overleaf.com/on-premises/user-and-project-management/roles-and-permissions)。
  *如果不介意一个更庞大的 Docker 镜像，[我们也准备好了](#docker-deployment) :)*
- TexLite 可在项目终端中直接运行宿主机安装的 Coding Agent CLI（比如Claude Code、Codex、OpenCode），让 agent 读取和编辑项目文件，由团队自主选择模型和工作流，而不局限于内建的 AI 聊天界面。

自托管并不保证每份文档都编译得更快，速度仍取决于宿主机和文档本身；它带来的是对容量、
TeX 更新、数据位置与协作工作流的掌控。

若是以个人、本地桌面工作流为主，建议优先考虑
[VS Code + LaTeX Workshop](https://github.com/James-Yu/LaTeX-Workshop) 或
[TeXstudio](https://texstudio.org/)。TexLite 的目标是浏览器中的共同写作，而不是取代个人 IDE。

## 核心写作工作流

- 项目支持文件夹、ZIP 导入/导出、标签、分享、所有权转让、归档和私有的个人引用库；引用库支持主题文件夹、标签、Markdown 笔记及整文件夹 BibTeX 导出，也可携带笔记导出并分享给其他用户。
  支持导入 `.bib` 文件或 TexLite JSON 导出文件。
- 所有者可创建免登录的只读链接，设置有效期、轮换或撤销；访客可查看源码和已有 PDF，
  不加入协作列表。
- 基于 CodeMirror 的编辑器提供 LaTeX/BibTeX 高亮、折叠、补全、可选 Vim 模式、格式化、
  拼写/语法/ChkTeX 辅助、搜索替换及源码/PDF SyncTeX 跳转。
- 基于 Yjs 的协同源码编辑支持活动会话、源码锚定批注、回复、解决状态，以及让审阅者
  可批注但不能修改源码的权限模型。
- 使用 `latexmk` 和可选择引擎进行编译，提供项目设置、结构化诊断、缓存的成功 PDF、
  可下载产物以及可选的项目级 `latexmkrc`。
- 每个项目拥有历史版本和仅所有者可用的 Git/GitHub 备份；Git 是可选依赖，仅在使用
  集成时才检查。
- 可选的网页终端可调用服务器上安装的代码 agent，由管理员启用。参见[外部 agent 终端](OPERATIONS.md#external-agent-terminals)。

<a id="docker-deployment"></a>

### Docker 部署

如果宿主机没有，或不希望自行维护 Node.js、TeX Live、Git 和 Harper 等软件，可使用更重的
[TexLite-Docker](https://github.com/SWUFE-DB-Group/TexLite-Docker) 部署。其已发布镜像会
一并提供这些运行时依赖。

当前 Docker 镜像未预装 Coding Agent CLI。如需使用此功能，推荐通过 npm 直接部署
TexLite，并在宿主机安装、配置所需 CLI。

```bash
git clone https://github.com/SWUFE-DB-Group/TexLite-Docker.git
cd texlite-docker
cp deployment.example.json deployment.json
# 首次启动前请编辑 deployment.json。
./scripts/compose.sh pull
./scripts/compose.sh up -d
# 访问 <http://127.0.0.1:3040>
```

Docker 版的用户配置和日常运维请参见
[TexLite-Docker README](https://github.com/SWUFE-DB-Group/TexLite-Docker#readme)。

## 文档导航

| 需要了解                                                       | 阅读                                                       |
| -------------------------------------------------------------- | ---------------------------------------------------------- |
| 安装、配置路径、生效默认值、环境变量、服务管理、备份与安全边界 | [运维指南（英文）](OPERATIONS.md)                          |
| 协作、源码持久化、编译隔离、历史版本和设计权衡                 | [设计文档（英文）](DESIGN.md)                              |
| TikZ 图库扩展（Beta） | [TikZ 图库扩展（英文）](addon.md) |
| 发布前测试 npm 包                                              | [NPM 测试指南（英文）](NPM_TESTING.md)                     |
| 完整配置起点                                                   | [texlite.config.example.json](texlite.config.example.json) |

## 范围与安全

TexLite 是面向小型可信团队的单宿主机应用。账号由管理员创建，项目权限由服务端校验。
它不是编译沙箱：LaTeX 本身以及启用的项目 `latexmkrc` 都可以在宿主机上执行强大的命令，
因此只应给可信的人开设账号。

**局域网内使用。** TexLite 默认监听 `127.0.0.1`，只有本机可以访问。若要让同一实验室或
办公网络中的同事使用，在 `texlite.config.json` 中把 `server.host` 设为 `0.0.0.0`
（或设置环境变量 `TEXLITE_HOST=0.0.0.0`），然后运行 `texlite restart`。其他人即可通过
`http://<宿主机 IP>:3000` 访问；如有需要，请在宿主机防火墙中放行该端口。
`texlite config` 会显示当前使用的配置文件。

**局域网外访问。** 请使用隧道或私有网络，不要在路由器上直接做端口转发。此时 TexLite
继续监听 `127.0.0.1`，所有项目仍由 TexLite 自身的登录保护。

<details>
<summary><b>TexLite Share</b>：为 TexLite 提供最简单的 HTTPS 链接</summary>

[TexLite Share](https://share.zhongpu.info/) 目前部署在香港，来自中国大陆或东南亚以外
地区的访问可能较慢。确保 TexLite 已在默认端口启动，然后安装并运行隧道客户端：

```bash
curl -fsSL https://raw.githubusercontent.com/ChenZhongPu/TexLite-Share/main/install-client.sh | bash
~/.local/bin/texlite-tunnel-client --server-url https://share.zhongpu.info
```

如果 TexLite 使用非默认端口，请明确指定本地地址：

```bash
~/.local/bin/texlite-tunnel-client \
  --server-url https://share.zhongpu.info \
  --local-addr 127.0.0.1:8080
```

</details>

其他常见选择包括
[Tailscale Serve](https://tailscale.com/docs/reference/tailscale-cli/serve)、
[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)
和 [frp](https://github.com/fatedier/frp)。

## 许可证

TexLite 使用 GNU Affero General Public License v3.0，详见 [LICENSE](LICENSE)。如需
闭源修改，或需要不同于 AGPL-3.0 的商业条款，请联系版权所有者。